Bitbucket MCP Server (Python)

Connect Claude Code, OpenAI Codex, Cursor, VS Code (GitHub Copilot), and any MCP-compatible AI assistant to your Bitbucket Cloud repositories. Review pull requests, monitor pipelines, and manage your code — all through natural language.

Features

• 60+ MCP tools — repositories, pull requests, comments, tasks, diffs, pipelines (runtime + config), build statuses, reviewers, draft PRs, batch review, issue tracker, commits, source/file browsing
• MCP 2025 tool annotations — every tool advertises readOnlyHint / destructiveHint / idempotentHint / openWorldHint + a human-readable title, so clients (Claude Code, Cursor) auto-include read-only tools and warn before destructive operations
• Slim responses — stripped API noise for lower LLM token usage
• Configurable — enable/disable tools via configs/tools.json or BITBUCKET_TOOLS_CONFIG env var
• Secure credentials — environment variables or system keychain

Quick Start

1. Install

The recommended way to run the server is via uvx (zero install, isolated environment):

# Always latest version
uvx --from bitbucket-mcp-py bitbucket-mcp

# Pin a specific version
uvx --from bitbucket-mcp-py==1.8.1 bitbucket-mcp

Why --from? The PyPI package is bitbucket-mcp-py but the command entry point is bitbucket-mcp. The --from flag tells uvx which package to install.

2. Configure credentials

Set the following environment variables (or use a .env file — see Credentials):

Get your API token at: https://id.atlassian.com/manage-profile/security/api-tokens

⚠️ Use a scoped token, not a global one. When creating the token, select specific scopes (e.g. Repositories: Read, Pull requests: Read/Write). Global tokens without explicit scopes do not work with this MCP server.

3. Configure your AI assistant

Claude Code (recommended)

Option A — CLI (fastest):

claude mcp add bitbucket-mcp \
  -e BITBUCKET_USERNAME=your-email@example.com \
  -e BITBUCKET_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

Option B — JSON config (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

OpenAI Codex

Option A — CLI (fastest):

codex mcp add bitbucket-mcp \
  --env BITBUCKET_USERNAME=your-email@example.com \
  --env BITBUCKET_TOKEN=your-api-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

Option B — TOML config (~/.codex/config.toml):

[mcp_servers.bitbucket-mcp]
command = "uvx"
args = ["--from", "bitbucket-mcp-py", "bitbucket-mcp"]
env = { BITBUCKET_USERNAME = "your-email@example.com", BITBUCKET_TOKEN = "your-api-token", BITBUCKET_WORKSPACE = "your-workspace" }

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (workspace) or ~/Library/Application Support/Code/User/mcp.json (global, macOS):

{
  "servers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Available Tools

Disabled by default: merge_pull_request (safety), stop_pipeline (safety), get_pull_request_patch (git am format — not useful for AI review), convert_pull_request_to_draft (not supported by Bitbucket API), delete_issue (safety), delete_issue_comment (safety), add_commit_comment (write op), create_pipeline_variable / update_pipeline_variable / delete_pipeline_variable (write ops), create_pipeline_schedule / update_pipeline_schedule / delete_pipeline_schedule (write ops), delete_pipeline_cache (safety), create_environment / delete_environment / create_deployment_variable / update_deployment_variable / delete_deployment_variable (write ops), create_branch_restriction / update_branch_restriction / delete_branch_restriction (write ops). Enable in configs/tools.json.

Governance scopes — Branch restriction read tools need the repository scope (repository:admin may be required depending on repo config); the write tools need repository:admin. Workspace member/permission tools need the account scope. The /members endpoint lists users without a per-user permission (use list_workspace_permissions for roles).

Deployments scopes — the read tools (list_environments, get_environment, list_deployments, get_deployment, list_deployment_variables) need the deployment scope; the write tools need deployment:write. Bitbucket has no server-side filter for deployments by environment (BCLOUD-18729) — filter on the environment field of list_deployments instead. There is no update_environment tool: Bitbucket exposes no PUT for environments (only POST .../changes for locking).

Custom tool configuration

By default the server reads configs/tools.json bundled with the package. You can point to a custom file at runtime without rebuilding:

export BITBUCKET_TOOLS_CONFIG=/path/to/my-tools.json

Fallback chain (first match wins):

1. BITBUCKET_TOOLS_CONFIG environment variable
2. Built-in configs/tools.json

Fail-safe behaviour — If BITBUCKET_TOOLS_CONFIG is set but the file is missing or contains invalid JSON, the server raises an error on startup (explicit failure rather than silently ignoring the override). If the built-in default is missing, all tools are enabled.

Token tip — get_pull_request_diff accepts an optional path parameter to filter the diff to a single file, reducing token usage by ~95% on large PRs:

get_pull_request_diff(repo_slug, pull_request_id, path="src/services/myService.ts")

MCP Prompts

The server also exposes MCP Prompts — parameterised templates that compatible clients (Claude Code, Cursor, ...) surface as slash commands. Instead of remembering tool names, you invoke a prompt and the assistant orchestrates the right tools for you. They appear in the client's prompt picker (prompts/list).

Prompts are enabled/disabled in configs/tools.json under the top-level prompts key (separate from tools).

Credentials

Option 1: .env file (recommended)

cp .env.example .env
# Edit .env with your credentials

Option 2: System keychain (most secure)

pip install 'bitbucket-mcp-py[keyring]'
python3 -c "import keyring; keyring.set_password('bitbucket-mcp', 'bitbucket_token', 'YOUR_TOKEN')"

Docker (Alternative)

If you prefer running the server in a container:

docker build -t bitbucket-mcp-py .
docker run -d --name bitbucket-mcp --env-file .env bitbucket-mcp-py

Then configure your AI assistant to use docker exec:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "bitbucket-mcp", "python", "-m", "src.main", "--transport", "stdio"]
    }
  }
}

Transports

The server speaks stdio by default (the standard transport for local MCP clients). For a network deployment it also supports Streamable HTTP (MCP spec 2025-03-26):

# Streamable HTTP on 0.0.0.0:8080
python -m src.main --transport http --host 0.0.0.0 --port 8080

Clients connect to http://<host>:<port>/mcp (e.g. http://localhost:8080/mcp).

--transport sse (legacy Server-Sent Events) is still accepted but deprecated — it emits a DeprecationWarning. Prefer --transport http.

Stateless HTTP (horizontal scaling / serverless)

--stateless runs the Streamable HTTP transport without server-side sessions: no Mcp-Session-Id, a fresh transport per HTTP request. Any instance behind a load balancer can serve any request — no sticky sessions required.

python -m src.main --transport http --host 0.0.0.0 --port 8080 --stateless

⚠️ Single-tenant only. The server serves its own process-wide Bitbucket token to every caller. Deploy it on a private network or behind an authenticated reverse proxy. Per-request credentials (multi-tenant) are tracked in #72.

--stateless requires --transport http (it is rejected on stdio and on the legacy sse, whose app ignores the setting). It also forces a single JSON response instead of an SSE stream, because edge/serverless runtimes cannot hold a streaming response open — there is currently no way to combine stateless with streaming.

A liveness endpoint is exposed on both HTTP transports for load balancers:

curl http://localhost:8080/healthz    # {"status": "ok"}

In a container — the image's default CMD keeps it idle for exec-based stdio usage, so server mode is started by overriding the command:

podman run -d --name bitbucket-mcp-http -p 8000:8000 --env-file .env bitbucket-mcp-py \
  python -m src.main --transport http --host 0.0.0.0 --port 8000 --stateless

Works identically with docker run. The image exposes port 8000.

The two allowlists must be set together: an empty Host allowlist rejects every request (421), and an empty Origin allowlist rejects every browser client (403). Setting only one is refused at startup rather than silently locking the server out.

export BITBUCKET_ALLOWED_HOSTS="mcp.example.com"
export BITBUCKET_ALLOWED_ORIGINS="https://app.example.com"

With neither allowlist set, no DNS-rebinding protection is applied — appropriate for a server reached through a private network or a trusted proxy. Set them as soon as the server is exposed on a real hostname.

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/test_client.py -v

Requirements

• Python 3.12+
• Bitbucket API token

License

MIT

References

• MCP Registry — Official MCP server registry
• PyPI Package — Python package
• MCP Python SDK
• Bitbucket API 2.0
• FastMCP Framework