MCP server for Bitbucket Cloud: repositories, pull requests, branches, tags, commits, diffs, files and pipelines, for Claude (claude.ai, Claude Desktop, Claude Code, mobile) and other AI agents that speak the Model Context Protocol.
It ships bb, a small Bitbucket Cloud command-line client written in standard-library Python, and bb mcp-serve, which serves that client over streamable HTTP as two MCP tools behind a bearer secret.
Two tools. Each takes {"args": [...]}: the words that would follow bb on a command line.
| Tool | What it runs |
|---|---|
bb_read |
Read-only commands. Nothing it runs changes anything. |
bb_write |
Commands that change something. Mark it "ask before use" in your client. |
Read-only commands (bb_read):
whoami,scopesrepo get,repo list [WORKSPACE]branch list [--name TEXT],branch get NAMEtag list,tag get NAMEcommit get HASH,commit list [REVISION] [--path P]diff SPEC,diffstat SPECfile get REF PATH,file list REF [PATH]pr list [--state …] [--author …] [--source B] [--dest B] [--title …]pr get | diff | diffstat | commits | activity | comments | tasks | statuses IDpipeline list [--branch B],pipeline get UUID,pipeline steps UUID,pipeline log UUID STEP_UUIDapi GET PATH [--query k=v] [--raw] [--paginate]
Commands that change something (bb_write):
branch create NAME --from REF,branch delete NAMEtag create NAME --from REF [--message …],tag delete NAMEpr create,pr update,pr comment,pr comment-edit,pr comment-deletepr task-create,pr task-update,pr task-deletepr approve,pr unapprove,pr request-changes,pr remove-request-changes,pr declinepr merge ID [--strategy squash|merge_commit|fast_forward]pipeline run --branch B [--pattern NAME],pipeline stop UUIDapi POST|PUT|DELETE PATH [--data JSON]
Every write accepts --dry-run. Output is JSON; --brief gives one line per item; --all follows every page.
- Linux or macOS with Python 3.8 or newer (standard library only)
- A Bitbucket Cloud account and an Atlassian API token with Bitbucket scopes
- Optional:
cloudflared, to reach the server from claude.ai and mobile
git clone <this repository's URL> bitbucket-mcp
cd bitbucket-mcp
pipx install . # or: python3 -m pip install --user .This installs two commands: bb and bb-auth.
Store the API token (create it at https://id.atlassian.com/manage-profile/security/api-tokens, "Create API token with scopes", app Bitbucket). bb-auth asks for your Atlassian email and the token, writes them to ~/.netrc (mode 600) under machine api.bitbucket.org, and checks them. The token is never printed.
bb-auth
bb whoami --briefAll settings are environment variables and all are optional. See config.example.env.
| Variable | Default | Meaning |
|---|---|---|
BB_DEFAULT_REPO |
none | Repository used when a command has no --repo, as WORKSPACE/SLUG |
BB_MCP_BIND |
127.0.0.1 |
Address the MCP server listens on. Keep it on the loopback interface |
BB_MCP_PORT |
8765 |
Port the MCP server listens on (--port overrides it) |
BB_MCP_SECRET_FILE |
~/.config/bb/mcp-secret |
File holding the bearer secret (mode 600) |
BB_MCP_PUBLIC_HOSTS |
none | Comma-separated public host names that may reach the server, e.g. a tunnel hostname |
bb mcp-serve --init-secret # create the bearer secret (prints its path only)
bb mcp-serve # serve on 127.0.0.1:8765
bb mcp-serve --show-header # print "Bearer …" (only when stdout is a terminal)
bb mcp-serve --rotate-secret # replace the secret, then restart and update clientsAs a systemd user service: copy examples/bitbucket-mcp.service to ~/.config/systemd/user/, set the path to bb, put your settings in ~/.config/bb/bitbucket-mcp.env, then:
systemctl --user daemon-reload
systemctl --user enable --now bitbucket-mcp
journalctl --user -u bitbucket-mcp -f # one line per requestclaude.ai (web, desktop and mobile): Settings → Connectors → Add custom connector. URL https://<your-public-host>/mcp, and an Authorization header with the value from bb mcp-serve --show-header. claude.ai needs a public HTTPS URL; see the tunnel section below.
Claude Code on the same machine:
claude mcp add --transport http bitbucket http://127.0.0.1:8765/mcp \
--header "Authorization: Bearer $(cat ~/.config/bb/mcp-secret)"cloudflared tunnel create <TUNNEL-NAME>
cloudflared tunnel route dns <TUNNEL-NAME> <MCP-HOSTNAME>Use examples/cloudflared.yml as the tunnel config, set BB_MCP_PUBLIC_HOSTS=<MCP-HOSTNAME>, and restart the service. The server itself still listens only on the loopback interface.
- Every request needs
Authorization: Bearer <secret>, compared in constant time. A wrong secret gets401; more than 10 failures a minute from one client get429for 60 seconds. - Requests whose
Hostis not127.0.0.1:<port>,localhost:<port>or a name inBB_MCP_PUBLIC_HOSTSget421. /.well-known/*answers404without the secret, so clients do not look for OAuth.- The Bitbucket token is only ever sent to
https://api.bitbucket.org. Redirects to other hosts have theAuthorizationheader removed. - Output is scrubbed of the token and the bearer secret before it is returned. Logs record the tool, the command and the exit code, never arguments' values or output.
- Through MCP, options that read local files (
--text-file,--data-file, …), absolute URLs forapi, and--confirm-delete-repositoryare refused. bb_readrefuses any write, andbb_writerefuses reads, so a client can auto-approvebb_readonly.- Commands run from an argument list, never through a shell, with a 90-second timeout and output capped at 100,000 characters.
Written by Febin Micheal Antony. Uses the Bitbucket Cloud REST API and the Model Context Protocol.