Bugzilla MCP Server

An MCP server that lets Claude and other AI assistants search, read, triage and update bugs in any Bugzilla 5.0+ instance.

• Runs on your machine: your Bugzilla API key never leaves it.
• Read-only by default: tools that change Bugzilla stay off until you turn them on, and update_bug has a dry run.
• Built for triage: batch reads, history, duplicates, classification, and screenshots that come through as images.

📖 Docs: bugzilla-mcp.vercel.app

Requirements

Start local; use the hosted server to try things out without installing anything.

	Local (recommended)	Hosted
Bugzilla	5.0+ with the REST API enabled	Same, reachable from the internet
API key	From your Bugzilla	Same
On your machine	uv or pipx (nothing for Claude Desktop's one-click install)	Nothing
MCP client	Any client that runs stdio servers	Any client with HTTP transport and custom headers
Your API key	Stays on your machine	Passes through bugzilla.fastmcp.app
Attachment downloads	Yes	No

Install

Claude Desktop: one click

1. Download bugzilla-mcp.mcpb from the latest release.
2. Double-click it (or open Settings → Extensions and install it there).
3. Enter your Bugzilla URL and API key. Leave Read-only ticked unless you want Claude to update bugs.

No Python or terminal needed. Claude Desktop stores the API key as a secret.

Claude Code

Install uv once, then:

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

Add --allow-writes after bugzilla-mcp to enable write tools. Check it with claude mcp list.

Cursor, VS Code and other MCP clients

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

If the client can't find uvx (desktop apps don't always load your shell's PATH), use the full path from which uvx.

pipx

pipx installs bugzilla-mcp into its own environment and puts the command on your PATH:

brew install pipx && pipx ensurepath   # macOS; see pipx docs for Linux/Windows
pipx install bugzilla-mcp
bugzilla-mcp --help

Then use bugzilla-mcp as the client command instead of uvx bugzilla-mcp:

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

If a desktop app can't find it, use the full path from which bugzilla-mcp (usually ~/.local/bin/bugzilla-mcp). Upgrade with pipx upgrade bugzilla-mcp.

Needs Python 3.12+. If pipx reports "No matching distribution found", it is using an older Python (macOS's python3 is 3.9): run pipx install --python python3.12 bugzilla-mcp.

Options

Setting	How	Default
Bugzilla URL	BUGZILLA_URL	required
API key	BUGZILLA_API_KEY (environment or .env only, never a flag)	required
Write tools	--allow-writes or BUGZILLA_READ_ONLY=false	off
Remove tools	BUGZILLA_DISABLED_TOOLS=update_bug,create_bug	none
Request timeout (seconds)	BUGZILLA_TIMEOUT	30
HTTP server for several users	bugzilla-mcp --transport http --host 0.0.0.0 --port 8000	stdio

See Configuration for every option.

API key

Create one in Bugzilla under Preferences → API Keys (https://your-bugzilla/userprefs.cgi?tab=apikey). The key has the same permissions as your account, so a dedicated account with limited access is safest.

Tools

28 tools, grouped by what they do. Full reference: Usage.

Group	Tools
Read	bug_info (compact by default, full / include_fields), bug_comments, bug_history, bug_dependencies, duplicate_chain, bug_url, server_url
Search	bugs_quicksearch, bugs_advanced_search, learn_quicksearch_syntax
Attachments	bug_attachments, get_attachment (images as images, logs and patches as text), upload_attachment
Batch and triage	bugs_info, bugs_comments, bugs_analysis_context, classify_bugs_heuristics, analyze_bugs_statistics
Users and products	get_user, search_users, list_products, get_product_components
Change (off until writes are enabled)	update_bug (with dry_run), create_bug, add_comment, tag_comment
Local only	download_attachments, download_attachment (save to disk)

Every tool carries MCP hints (read-only / destructive), so clients can run reads without asking and confirm before changes.

Hosted server (FastMCP Cloud)

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

Header	Required	Value
api_key	yes	Your Bugzilla API key
bugzilla_url	yes	Your Bugzilla's base URL (5.0+)
read_only	no	false to enable write tools (default true)

Your API key passes through the hosted server on its way to your Bugzilla. It's great for trying things out; for day-to-day use, install locally.

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 (via mcp-remote, needs Node.js)

{
  "mcpServers": {
    "bugzilla": {
      "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": {
      "url": "https://bugzilla.fastmcp.app/mcp",
      "headers": {
        "api_key": "your-api-key",
        "bugzilla_url": "https://bugzilla.example.com"
      }
    }
  }
}

VS Code (.vscode/mcp.json)

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

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

Security

• The server starts read-only. Enable writes only for an account that should be allowed to change bugs.
• Use a dedicated Bugzilla account with limited access; never an admin account.
• Your key goes to Bugzilla in the X-BUGZILLA-API-KEY header. Stock Bugzilla 5.0/5.2 ignore that header, so for them it falls back to ?api_key= (deprecated; keep query strings out of your web server's access logs).

More: Security.

Development

git clone https://github.com/SanthoshSiddegowda/bugzilla-mcp.git
cd bugzilla-mcp
uv sync --all-extras
uv run pytest tests
uv run bugzilla-mcp --help

Contributor notes are in CLAUDE.md. Releases publish to PyPI and attach the Claude Desktop extension automatically when a GitHub release is published.

Acknowledgments

Inspired by Sai Karthik's mcp-bugzilla. Thank you for sharing your work with the MCP community. Looking for openSUSE's server? That's mcp-bugzilla, a separate project.

License

Apache 2.0