bitbucket-mcp

A Model Context Protocol server for Bitbucket Cloud. Review, manage, and merge pull requests, assign reviewers by name, read files at a ref, and inspect pipeline status — from any MCP client (Claude Desktop, Cursor, Claude Code) or a hosted HTTP endpoint.

It talks to the Bitbucket Cloud REST API v2.0 with a single access token. All read paths are paginated and capped; write tools (create/merge PR, comments, reviewers) are explicit.

Tools

All tools are prefixed bb_.

Assigning reviewers by name

Bitbucket's /workspaces/{workspace}/members endpoint requires the account scope (which PR tokens don't carry), so you can't resolve a person's name to their account UUID over the API. This server keeps a small local directory of known members so bb_add_pull_request_reviewers accepts a plain name (e.g. "Jane Doe") and resolves it offline. Raw account UUIDs always work too.

Seed people in either place (both use the same JSON shape; the env var merges on top of the file):

• tools/bitbucket/directory.json — copy directory.example.json and fill it in. This file is git-ignored so real account UUIDs never get committed.

• BITBUCKET_KNOWN_MEMBERS env var — handy for hosted deploys.

{
  "your-workspace-slug": [
    { "uuid": "{00000000-0000-0000-0000-000000000000}", "display_name": "Jane Doe", "nickname": "Jane" }
  ]
}

Related MCP server: Bitbucket MCP

Configuration

Set via environment variables (see .env.example). Prefix BITBUCKET_.

Tools are always listed but return a clear "not configured" error if BITBUCKET_API_KEY is missing, so the server starts cleanly without secrets.

Quick start (local, stdio)

Requires Python 3.11+.

git clone https://github.com/matt-nann/bitbucket-mcp.git
cd bitbucket-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export BITBUCKET_API_KEY=your-token
python server.py            # stdio (default)

Wire it into an MCP client

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

{
  "mcpServers": {
    "bitbucket": {
      "command": "python",
      "args": ["/absolute/path/to/bitbucket-mcp/server.py"],
      "env": {
        "BITBUCKET_API_KEY": "your-token",
        "BITBUCKET_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Claude Code:

claude mcp add bitbucket \
  --env BITBUCKET_API_KEY=your-token \
  --env BITBUCKET_WORKSPACE=your-workspace-slug \
  -- python /absolute/path/to/bitbucket-mcp/server.py

Hosting (HTTP)

The same server runs over streamable HTTP for a shared/hosted deployment. It binds dual-stack IPv6 and honors $PORT, so it works on Railway (and Fly/Heroku/Docker) out of the box:

MCP_TRANSPORT=http PORT=8000 python server.py --http
# MCP endpoint: http://localhost:8000/mcp   health: /health

⚠️ HTTP mode has no built-in authentication and every request uses the one BITBUCKET_API_KEY identity. Don't expose it publicly without an auth proxy in front. See HOSTING.md for the full Railway walkthrough, Docker instructions, and the security model.

Provenance

Extracted from a larger internal multi-tool MCP server into a standalone, self-contained package. No internal identifiers or shared auth layers are included; the member directory ships only as a placeholder example.

License

MIT