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

Tool	What it does
bb_list_pull_requests	List PRs in a repo, filtered by state
bb_get_pull_request	Full detail for one PR
bb_get_pull_request_diff	Unified diff for a PR
bb_get_pull_request_comments	All comments on a PR (inline + general)
bb_get_pull_request_status	Aggregated build/status checks for a PR
bb_get_pipeline_status	Commit statuses for an arbitrary ref
bb_create_pull_request	Open a PR (optionally with reviewers)
bb_merge_pull_request	Merge a PR (merge_commit / squash / fast_forward)
bb_create_pull_request_comment	Add a comment (optionally inline on a file/line)
bb_edit_pull_request_comment	Edit one of your comments
bb_delete_pull_request_comment	Delete one of your comments
bb_add_pull_request_reviewers	Assign reviewers by name or UUID
bb_list_workspace_members	Inspect the local known-members directory
bb_get_file	Read a file's contents at a branch/commit

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" }
  ]
}

Configuration

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

Variable	Required	Description
BITBUCKET_API_KEY	✅	Access token (Bearer) or app password
BITBUCKET_USERNAME	—	Set only when using an app password (switches to Basic auth)
BITBUCKET_WORKSPACE	—	Default workspace slug, so tools don't need it each call
BITBUCKET_DEFAULT_REPO	—	Default repo slug
BITBUCKET_KNOWN_MEMBERS	—	JSON of extra known members (merged over directory.json)
BITBUCKET_MAX_PAGES	—	Pagination cap (default 10)
BITBUCKET_TIMEOUT	—	HTTP timeout in seconds (default 30)

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