Skip to content

Latest commit

 

History

History
132 lines (95 loc) · 6.24 KB

README.md

File metadata and controls

132 lines (95 loc) · 6.24 KB

bitbucket-mcp

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.

Features

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, scopes
  • repo get, repo list [WORKSPACE]
  • branch list [--name TEXT], branch get NAME
  • tag list, tag get NAME
  • commit get HASH, commit list [REVISION] [--path P]
  • diff SPEC, diffstat SPEC
  • file 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 ID
  • pipeline list [--branch B], pipeline get UUID, pipeline steps UUID, pipeline log UUID STEP_UUID
  • api GET PATH [--query k=v] [--raw] [--paginate]

Commands that change something (bb_write):

  • branch create NAME --from REF, branch delete NAME
  • tag create NAME --from REF [--message …], tag delete NAME
  • pr create, pr update, pr comment, pr comment-edit, pr comment-delete
  • pr task-create, pr task-update, pr task-delete
  • pr approve, pr unapprove, pr request-changes, pr remove-request-changes, pr decline
  • pr merge ID [--strategy squash|merge_commit|fast_forward]
  • pipeline run --branch B [--pattern NAME], pipeline stop UUID
  • api POST|PUT|DELETE PATH [--data JSON]

Every write accepts --dry-run. Output is JSON; --brief gives one line per item; --all follows every page.

Requirements

  • 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

Install

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 --brief

Configure

All 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

Run

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 clients

As 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 request

Connect to Claude

claude.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)"

Optional: expose over Cloudflare Tunnel

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.

Security notes

  • Every request needs Authorization: Bearer <secret>, compared in constant time. A wrong secret gets 401; more than 10 failures a minute from one client get 429 for 60 seconds.
  • Requests whose Host is not 127.0.0.1:<port>, localhost:<port> or a name in BB_MCP_PUBLIC_HOSTS get 421.
  • /.well-known/* answers 404 without 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 the Authorization header 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 for api, and --confirm-delete-repository are refused.
  • bb_read refuses any write, and bb_write refuses reads, so a client can auto-approve bb_read only.
  • Commands run from an argument list, never through a shell, with a 90-second timeout and output capped at 100,000 characters.

Credits

Written by Febin Micheal Antony. Uses the Bitbucket Cloud REST API and the Model Context Protocol.

License

MIT