Getting Started

Security

Security best practices for using the Bugzilla MCP Server.

Security Overview

The Bugzilla MCP Server requires Bugzilla API access to function. Following security best practices is essential to protect your Bugzilla instance and data.

API Key Security

Create Dedicated API Keys

Never use administrative accounts or full-access API keys with the MCP server.

Create a dedicated Bugzilla user account for MCP access
Generate a dedicated API key with minimal required permissions
Use separate API keys for different environments (development, production)

API Key Permissions

A Bugzilla API key has the same permissions as the account that created it. You can't scope the key itself, so limit the account instead:

Restrict group membership and product access to what the assistant needs to see
Writes are possible: the add_comment tool posts comments (including private ones) as this account. Give the account no edit rights on products where it shouldn't comment
Avoid administrative accounts: never use an account with admin or editbugs-everywhere privileges

API Key Storage

Never commit API keys or credentials to version control.

Best Practices:

Store API keys in secure configuration files (not in code)
Use environment variables when possible
Never share API keys in public repositories
Rotate API keys regularly
Revoke compromised keys immediately

Configuration Security

Secure Configuration Files

Claude Code:

Add the server with --scope user so the key is stored in ~/.claude.json, not the repository
In a shared .mcp.json, use ${BUGZILLA_API_KEY} / ${BUGZILLA_URL} instead of literal values

Claude Desktop:

File location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Ensure proper file permissions (readable only by your user)

Cursor IDE:

File location: .cursor/mcp.json
Add to .gitignore if in a repository
Use environment variables for sensitive values when possible

Visual Studio Code:

Store mcp.json securely
Don't commit to version control

Environment Variables

The server itself does not read environment variables. Credentials always come from the request headers your MCP client sends. Environment variables are still useful in the client config so the key isn't written into a file. For example, Claude Code expands ${VAR} in .mcp.json:

export BUGZILLA_API_KEY="your-api-key"
export BUGZILLA_URL="https://bugzilla.example.com"

"headers": {
  "api_key": "${BUGZILLA_API_KEY}",
  "bugzilla_url": "${BUGZILLA_URL}"
}

Network Security

Use HTTPS

Always use HTTPS for Bugzilla URLs in production environments.

Production: Always use https:// URLs
Development: Use https:// when possible, even for local instances
Never use HTTP for production Bugzilla instances

Hosted Server

The hosted production server at https://bugzilla.fastmcp.app/mcp:

Uses HTTPS for secure connections
Receives your API key and Bugzilla URL in request headers on every call
Forwards the key to your Bugzilla instance in the X-BUGZILLA-API-KEY header. Stock Bugzilla 5.0/5.2 ignore that header, so for them the key is sent as ?api_key= instead (deprecated, see Deprecations)
Creates a separate Bugzilla client for each request, so concurrent users never share credentials

Using the hosted server means your API key passes through a third-party server. If that's not acceptable for your organization, run the server locally and point your client at http://127.0.0.1:8000/mcp.

Hosted vs Local Server

	Hosted (`server.py`)	Local stdio (`server_local.py`)
Users	Many, at the same time	Just you
Credentials	Request headers, one client per request	Environment variables / `.env`
Write tools	Off by default; `read_only: false` header	Off by default; `BUGZILLA_READ_ONLY=false`
Tools that save to the server's disk (`download_attachment(s)`)	Not offered	Offered (with writes enabled)
`upload_attachment` from a `file_path`	Refused	Allowed
Attachments	`get_attachment` returns content inline	Inline, or saved to disk

On the hosted server, download_attachment(s) aren't offered and upload_attachment(file_path=...) is refused, on purpose. A shared server that wrote or read files at a caller's request would let anyone fill its disk or send its files (for example its .env) to their own Bugzilla.

Write Tools

The server starts in read-only mode, so these tools are hidden until you enable them. update_bug, create_bug, add_comment, upload_attachment and tag_comment change data in Bugzilla as your account. Every tool carries MCP hints (read-only, adds data, or destructive for update_bug), so clients can ask before running changes. Keep approval prompts on for write tools, and limit what the account itself can edit. Before a bulk update_bug, ask for a dry_run to see every change first.

Deprecations

API key in the query string (Bugzilla 5.0 / 5.2)

The server sends your API key to Bugzilla in the X-BUGZILLA-API-KEY header, which keeps it out of URLs and access logs. Stock Bugzilla 5.0 and 5.2 don't read that header, so for those instances the server falls back to sending the key as ?api_key= (the previous behaviour) and logs a deprecation warning.

Nothing breaks: existing setups keep working with no config changes.
The server detects support automatically, once per Bugzilla URL, using a probe that never sends your real key.
bugzilla.mozilla.org and Bugzilla master already use the header.
The query-string fallback will be removed once a stable Bugzilla release supports the header. Until then, if your Bugzilla runs 5.0/5.2, make sure its web server and any proxies don't keep query strings in access logs.