Configuration

Overview

There are two ways to run the server, and they take settings differently:

Most people should run it locally. See Installation for the one-click and one-command installs.

Getting Your API Key

1. Open your Bugzilla's API key page: https://your-bugzilla-instance.com/userprefs.cgi?tab=apikey
2. Generate a new key and copy it.

The key has the same permissions as your account. A dedicated account with limited access is safest. See Security.

Local Settings

• BUGZILLA_URL needs Bugzilla 5.0+. https:// is added if you leave it off, and a trailing slash is ignored.
• The API key is only read from the environment or a .env file in the current directory, never a command-line flag: flags show up in process lists and shell history.
• bugzilla-mcp --help lists every flag; bugzilla-mcp --version prints the installed version.

Read-only Mode

The server starts in read-only mode. Tools that read from Bugzilla work normally; tools that change it (update_bug, create_bug, add_comment, upload_attachment, tag_comment) are hidden and refused. You can point it at a production Bugzilla without risk.

To enable write tools:

Even with writes enabled, every tool carries MCP hints (read-only, adds data, or destructive for update_bug), so clients like Claude can still ask before each change. Before a bulk change, ask for an update_bug dry run.

Turning off individual tools

BUGZILLA_DISABLED_TOOLS takes a comma-separated list of tool names, e.g. update_bug,create_bug. Those tools aren't registered at all. This works for any server you run yourself, local or HTTP.

Claude Desktop

Recommended: install the one-click extension. It shows a form for the URL, API key (stored as a secret) and the Read-only checkbox, and needs no Python.

To configure it by hand instead, open Settings → Developer → Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "bugzilla": {
      "command": "uvx",
      "args": ["bugzilla-mcp"],
      "env": {
        "BUGZILLA_URL": "https://bugzilla.example.com",
        "BUGZILLA_API_KEY": "your-api-key"
      }
    }
  }
}

Fully quit Claude Desktop (Cmd+Q on macOS) and reopen it. Desktop apps don't always load your shell's PATH; if the server doesn't start, set command to the full path from which uvx (e.g. /Users/you/.local/bin/uvx).

Claude Code

claude mcp add bugzilla --scope user \
  -e BUGZILLA_URL=https://bugzilla.example.com \
  -e BUGZILLA_API_KEY=your-api-key \
  -- uvx bugzilla-mcp

--scope user makes it available in every project and keeps the key in your user config (~/.claude.json), not in a repository. Check it with claude mcp list, then start a new session.

Sharing with a team

Commit a .mcp.json at the project root that reads the URL and key from each developer's environment:

{
  "mcpServers": {
    "bugzilla": {
      "command": "uvx",
      "args": ["bugzilla-mcp"],
      "env": {
        "BUGZILLA_URL": "${BUGZILLA_URL}",
        "BUGZILLA_API_KEY": "${BUGZILLA_API_KEY}"
      }
    }
  }
}

Each developer exports BUGZILLA_URL and BUGZILLA_API_KEY in their shell before starting Claude Code.

Cursor

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects):

{
  "mcpServers": {
    "bugzilla": {
      "command": "uvx",
      "args": ["bugzilla-mcp"],
      "env": {
        "BUGZILLA_URL": "https://bugzilla.example.com",
        "BUGZILLA_API_KEY": "your-api-key"
      }
    }
  }
}

Visual Studio Code

In .vscode/mcp.json. The inputs block makes VS Code ask for the key once and store it securely, so it never sits in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "bugzilla-api-key",
      "description": "Bugzilla API key",
      "password": true
    }
  ],
  "servers": {
    "bugzilla": {
      "type": "stdio",
      "command": "uvx",
      "args": ["bugzilla-mcp"],
      "env": {
        "BUGZILLA_URL": "https://bugzilla.example.com",
        "BUGZILLA_API_KEY": "${input:bugzilla-api-key}"
      }
    }
  }
}

Running Your Own HTTP Server

To serve several users from one machine:

bugzilla-mcp --transport http --host 0.0.0.0 --port 8000

Clients then connect to http://your-host:8000/mcp and send their own credentials as headers, exactly like the hosted server. In this mode the server never reads from or writes to its own disk: download_attachment(s) aren't offered, and uploads from a file path are refused. BUGZILLA_READ_ONLY sets the default for every connection, and BUGZILLA_DISABLED_TOOLS still applies.

Hosted Server

Nothing to install: connect to https://bugzilla.fastmcp.app/mcp, hosted on FastMCP Cloud, and send your credentials as headers.

Clients send these headers:

Claude Code:

claude mcp add --transport http bugzilla https://bugzilla.fastmcp.app/mcp --scope user \
  --header "api_key: your-api-key" \
  --header "bugzilla_url: https://bugzilla.example.com"

Claude Desktop connects to HTTP servers with custom headers through the mcp-remote bridge (needs Node.js):

{
  "mcpServers": {
    "bugzilla-hosted": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://bugzilla.fastmcp.app/mcp",
        "--header", "api_key:your-api-key",
        "--header", "bugzilla_url:https://bugzilla.example.com"
      ]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "bugzilla-hosted": {
      "url": "https://bugzilla.fastmcp.app/mcp",
      "headers": {
        "api_key": "your-api-key",
        "bugzilla_url": "https://bugzilla.example.com"
      }
    }
  }
}

VS Code (.vscode/mcp.json). The inputs prompt keeps the key out of the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "bugzilla-api-key",
      "description": "Bugzilla API key",
      "password": true
    }
  ],
  "servers": {
    "bugzilla-hosted": {
      "type": "http",
      "url": "https://bugzilla.fastmcp.app/mcp",
      "headers": {
        "api_key": "${input:bugzilla-api-key}",
        "bugzilla_url": "https://bugzilla.example.com"
      }
    }
  }
}

Add read_only: false to the headers (or "--header", "read_only:false" for mcp-remote) to enable write tools.

Verifying Configuration

1. Restart your MCP client.
2. Check the Bugzilla server appears in its list of MCP servers (claude mcp list in Claude Code).
3. Ask your assistant something like "Show me bug 12345" or "Search for open bugs in product X".

Troubleshooting

No matching distribution found for bugzilla-mcp

Your installer is using a Python older than 3.12, which is common on macOS, where python3 is Apple's Python 3.9. With pipx, pick a newer one: pipx install --python python3.12 bugzilla-mcp. Or use uvx bugzilla-mcp, which picks a suitable Python for you.

The client can't start the server / uvx: command not found

Install uv. If it is installed but a desktop app still can't find it, use the full path from which uvx as the command.

set BUGZILLA_URL and BUGZILLA_API_KEY

The local server didn't get its settings. Check the env block of your client config (or -e options for claude mcp add) for typos.

Write tools are missing

The server is in read-only mode, on purpose. Enable writes as described there.

api_key / bugzilla_url header is required (hosted or HTTP server)

Your client isn't sending that header. The names must be exactly api_key and bugzilla_url. In Claude Code, claude mcp get bugzilla shows the configured headers.

Authentication errors

• Check the API key is correct and hasn't been revoked.
• Check your Bugzilla allows REST API access (Bugzilla 5.0+).
• On Bugzilla 5.0/5.2 a log warning about the query-string fallback is expected and harmless. See Deprecations.

Next Steps

• Usage: every tool with examples
• Security: API key and deployment best practices