Configuration

Overview

The Bugzilla MCP Server requires HTTP headers for authentication. You need to configure your MCP client with:

• api_key (Required) - Your Bugzilla API key
• bugzilla_url (Required) - The base URL of your Bugzilla instance (Bugzilla 5.0+). https:// is added if you leave off the scheme, and a trailing slash is ignored

Getting Your API Key

1. Navigate to your Bugzilla instance's API key page:

   https://your-bugzilla-instance.com/userprefs.cgi?tab=apikey
   

2. Generate a new API key if you don't have one
3. Copy the API key (you'll need it for configuration)

Server URLs

• Production (Hosted): https://bugzilla.fastmcp.app/mcp
• Local Development: http://127.0.0.1:8000/mcp

Read-only Mode

The server starts in read-only mode: only tools that read from Bugzilla are offered, and tools that change data (update_bug, create_bug, add_comment, upload_attachment, tag_comment) are hidden and refused. You can try it against a production Bugzilla without risk.

To enable write tools:

• Hosted / HTTP server: send the header read_only: false. With Claude Code:

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

  With mcp-remote (Claude Desktop), add "--header", "read_only:false" to args. In url/headers configs (Cursor, VS Code), add "read_only": "false" to headers.
• Local stdio server (server_local.py): set BUGZILLA_READ_ONLY=false in the environment or .env.

If you run your own HTTP server, BUGZILLA_READ_ONLY=false changes its default; clients can still send read_only: true or false per connection.

Turning off individual tools

Set BUGZILLA_DISABLED_TOOLS to a comma-separated list of tool names, e.g. BUGZILLA_DISABLED_TOOLS=update_bug,create_bug. Those tools are not registered at all. This applies to servers you run yourself (local stdio or your own HTTP server).

Claude Code

Add the server with the Claude Code CLI:

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

--scope user makes the server available in all your projects and stores the key in your user config (~/.claude.json), not in the repository.

Verify it is connected:

claude mcp list

Then start a new Claude Code session so the tools load.

Sharing with a team

To check the configuration into a repository, create a .mcp.json at the project root and reference environment variables instead of hardcoding the key:

{
  "mcpServers": {
    "bugzilla": {
      "type": "http",
      "url": "https://bugzilla.fastmcp.app/mcp",
      "headers": {
        "api_key": "${BUGZILLA_API_KEY}",
        "bugzilla_url": "${BUGZILLA_URL}"
      }
    }
  }
}

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

Claude Desktop

Claude Desktop's claude_desktop_config.json only supports local (stdio) servers, so remote servers with custom headers must be connected through the mcp-remote bridge. This requires Node.js.

The location of this file depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

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

Restart Claude Desktop after saving.

Cursor IDE

Add this configuration to your .cursor/mcp.json:

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

Visual Studio Code

Add this configuration to your mcp.json:

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

Configuration Examples

Example: Bugzilla Mozilla

{
  "mcpServers": {
    "bugzilla": {
      "url": "https://bugzilla.fastmcp.app/mcp",
      "headers": {
        "api_key": "YOUR_MOZILLA_API_KEY",
        "bugzilla_url": "https://bugzilla.mozilla.org"
      }
    }
  }
}

Example: Custom Bugzilla Instance

{
  "mcpServers": {
    "bugzilla": {
      "url": "https://bugzilla.fastmcp.app/mcp",
      "headers": {
        "api_key": "YOUR_CUSTOM_API_KEY",
        "bugzilla_url": "https://bugs.yourcompany.com"
      }
    }
  }
}

Verifying Configuration

After configuring your MCP client:

1. Restart your MCP client (Claude Code, Claude Desktop, Cursor, or VS Code)
2. The Bugzilla MCP Server should appear in your available MCP servers
3. You can test the connection by asking your AI assistant to:
   • Get information about a bug
   • Search for bugs
   • Get the server URL

Troubleshooting

Missing Header Errors

If tool calls fail with `api_key` header is required or `bugzilla_url` header is required, your client isn't sending that header. Check the header names: they must be exactly api_key and bugzilla_url. For Claude Code, run claude mcp get bugzilla to see the configured headers.

Server Not Connecting

• Verify your API key is correct
• Check that your Bugzilla URL is accessible
• Ensure the server URL is correct (production or local)
• Check your MCP client logs for error messages

Authentication Errors

• Verify your API key has the necessary permissions
• Ensure your Bugzilla instance allows API access (REST API, Bugzilla 5.0+)
• On Bugzilla 5.0/5.2, a server log warning about the query-string fallback is expected and harmless. See Deprecations
• Check that the API key hasn't expired or been revoked

Local Development Issues

• Make sure the local server is running (python server.py)
• Verify the server is accessible at http://127.0.0.1:8000/mcp
• Check firewall settings if the connection fails

Next Steps

• Learn about usage examples
• Review security best practices