Bugzilla MCP
Getting Started

Installation

Get started with Bugzilla MCP Server.

Install (Recommended)

The server runs on your machine, so your Bugzilla API key never leaves it. It starts read-only; see Read-only Mode to enable write tools.

First, get an API key from your Bugzilla: https://your-bugzilla-instance.com/userprefs.cgi?tab=apikey.

Claude Desktop: one click

  1. Download bugzilla-mcp.mcpb from the latest release.
  2. Double-click it, or install it from Settings → Extensions.
  3. Enter your Bugzilla URL and API key. Untick Read-only only if Claude should update bugs.

No Python or terminal needed.

Claude Code

Install uv, then:

Terminal
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.

Cursor, VS Code and other 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, use the full path from which uvx.

pip

Terminal
pip install bugzilla-mcp
bugzilla-mcp --help

bugzilla-mcp --transport http runs it as a multi-user HTTP server instead, taking credentials from each request's headers.

Try the Hosted Server

To try it without installing anything, point your client at https://bugzilla.fastmcp.app/mcp with your API key and Bugzilla URL as headers (see Configuration). Your key passes through that server, so install locally for real use.

Run from Source

To run the server from a checkout (for development or testing):

Prerequisites

  • Python 3.12 or higher
  • uv package manager (recommended) or pip

Install dependencies

Using uv (recommended):

Terminal
uv sync

Or with standard Python:

Terminal
pip install .

Run the server

Using uv:

Terminal
uv run python server.py

Or with standard Python:

Terminal
python server.py

The server will start at http://127.0.0.1:8000/mcp/

Configure your MCP client

For local development, use http://127.0.0.1:8000/mcp as the server URL in your MCP client configuration.

Local stdio Server from a Checkout

server_local.py runs the server as a process your MCP client starts itself. Credentials come from environment variables (or a .env file), so your API key never goes to a hosted server. It is single-user, and it is the only mode where the tools that read or write files on disk (download_attachment(s), upload_attachment with file_path) are enabled.

Terminal
cp .env.example .env   # then set BUGZILLA_URL and BUGZILLA_API_KEY

Claude Code:

Terminal
claude mcp add bugzilla-local --scope user -- uv run --directory /absolute/path/to/bugzilla-mcp python server_local.py

Claude Desktop / Cursor (claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "bugzilla-local": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/bugzilla-mcp", "python", "server_local.py"],
      "env": {
        "BUGZILLA_URL": "https://bugzilla.example.com",
        "BUGZILLA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Development Setup

For contributing to the project:

Clone the repository

Terminal
git clone https://github.com/SanthoshSiddegowda/bugzilla-mcp.git
cd bugzilla-mcp

Install dependencies

uv creates the virtual environment for you:

Terminal
uv sync --all-extras

Run the tests

Terminal
uv run pytest tests

Inspect the server

You can inspect the MCP server to see available tools:

Terminal
uv run fastmcp inspect server.py:mcp

This will show you all available tools, their parameters, and descriptions.

Next Steps

Introduction

Welcome to Bugzilla MCP Server documentation.

Configuration

Configure the Bugzilla MCP Server with your MCP client.