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 — in your MCP client's env block, as shown above, or in the system keychain (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")

Token tip — get_pipeline_step_logs returns only the trailing 100 KiB of a step log by default (raw logs run to several MB on long steps). The response carries a truncated flag; widen the window with the absolute byte range start / end, or pass max_bytes=null for the whole log. Pass a service container UUID as log_uuid to read that service's log instead of the build container's. This endpoint needs a real pipeline UUID — resolve it via get_pipeline_run if you only have a build number.

get_pipeline_step_logs(repo_slug, pipeline_uuid="{adab6a1f-...}", step_uuid="{84fc6465-...}")

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: environment variables (recommended)

Put them in the env block of your MCP client configuration, as in the examples above, or export them in the shell that launches the server.

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')"

About .env: the server itself never reads a .env file. .env.example is a template for containers, which load it with --env-file .env or env_file: (the Docker, Makefile and docker-compose.yml setups); with uvx or python -m src.main, use option 1 or 2.

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 localhost:8080
python -m src.main --transport http --host 127.0.0.1 --port 8080

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

⚠️ --host defaults to 0.0.0.0, every interface. Without --multi-tenant the server has no authentication of its own: anyone who can reach the port acts with your Bitbucket token. Bind to 127.0.0.1 unless the port sits behind an authenticating proxy.

--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 by default. Without --multi-tenant the server serves its own process-wide Bitbucket token to every caller. Deploy it on a private network or behind an authenticated reverse proxy — or use multi-tenant mode, where each caller brings their own credentials.

--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 127.0.0.1:8000:8000 --env-file .env bitbucket-mcp-py \
  python -m src.main --transport http --host 0.0.0.0 --port 8000 --stateless

Inside the container --host 0.0.0.0 is required; -p 127.0.0.1:8000:8000 is what keeps the published port off the network, since this single-tenant server answers every caller with the .env token.

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.

Multi-tenant HTTP (per-request credentials)

By default an HTTP deployment is single-tenant: every caller acts with the process-wide Bitbucket token. --multi-tenant changes that — each request carries the caller's own Bitbucket OAuth access token as Authorization: Bearer, and runs under that identity. The server holds no Bitbucket credential of its own.

BITBUCKET_RESOURCE_SERVER_URL=https://mcp.example.com/mcp \
  python -m src.main --transport http --host 0.0.0.0 --port 8080 --stateless --multi-tenant

The token is verified against GET /2.0/user, which yields the caller's account_id and default workspace; the same token is then reused for the downstream API calls, so no credential is ever stored or mapped. Unauthenticated requests get a 401 with a WWW-Authenticate challenge pointing at /.well-known/oauth-protected-resource/mcp. Since Bitbucket publishes no OAuth metadata, the server serves /.well-known/oauth-authorization-server itself, pointing at Bitbucket's endpoints — which is what lets it be added to claude.ai as a custom connector (Bitbucket sign-in through the Atlassian login); setup, what was verified and the residual risks in docs/deployment-modes.md.

What this buys you:

• Isolation — one Bitbucket client per (identity, workspace); two callers never share one, and there is no process token to fall back on.
• workspace=None means your workspace — resolved from the caller's memberships, never from BITBUCKET_WORKSPACE. With zero or several memberships there is no default and calls must name their workspace.
• Audit trail — every call is logged to the bitbucket_mcp.audit logger with the tool, the account_id and the workspace. Never credentials.
• Tighter defaults — tools flagged destructiveHint are refused unless explicitly enabled. The other write tools (comment, approve, create a pull request, run a pipeline…) stay available to every caller: set BITBUCKET_MULTITENANT_READ_ONLY=1 for a first deployment.

Spec deviation: the caller's Bitbucket token is accepted without an audience check and forwarded upstream as-is, which the MCP authorization spec (2025-11-25) forbids — trade-offs and residual risks in docs/deployment-modes.md.

Not supported in this mode: Bitbucket Repository/Workspace Access Tokens — they are not bound to a user account, so no identity can be derived. Use single-tenant HTTP for that. Bearer tokens require TLS: terminate HTTPS in front of the server.

stdio is unaffected — it stays single-user with environment variables, exactly as documented above.

See docs/deployment-modes.md for the full matrix of the three deployment modes and the threat model of each.

Kubernetes (k3s, datacenter, GKE)

Each release publishes a multi-arch image (ghcr.io/lawp09/bitbucket-mcp) and a Helm chart (oci://ghcr.io/lawp09/charts/bitbucket-mcp) that deploy the multi-tenant HTTP mode; publicUrl is the only required value:

helm upgrade --install bitbucket-mcp oci://ghcr.io/lawp09/charts/bitbucket-mcp --version <version> \
  -n bitbucket-mcp --create-namespace --set publicUrl=https://mcp.example.com

Ingress, GKE and network-policy notes: docs/deployment-kubernetes.md.

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