bitbucket-mcp

A Model Context Protocol server for Bitbucket Cloud, optimized for use with Claude Code. Lets the agent read pull request diffs, read and write PR comments (including file + line inline comments), edit the PR Overview (title and description), resolve and unresolve comment threads, and read Bitbucket Pipelines step logs so it can debug failing builds.

Status: alpha. Distributed on npm as @mcpkits/bitbucket.

Tools

Read-only:

Tool	Description
get_pr	Fetch a PR's metadata (title, state, author, branches, URL).
list_prs	List PRs filtered by state, author, or branch.
get_pr_diff	Unified diff for a PR.
list_pr_comments	All comments on a PR (general + inline).
get_pr_pipeline_status	Pipelines triggered by a PR, with each step's pass/fail.
get_pipeline_step_log	Raw log output for a specific pipeline step.

Write:

Tool	Description
add_pr_comment	Post a general comment on a PR.
add_pr_inline_comment	Post a comment on a specific file + line in a PR's diff.
reply_to_pr_comment	Post a threaded reply to an existing PR comment (general or inline).
create_pr	Open a new PR. Defaults source to the current git branch.
update_pr	Update a PR's title, description (Overview), and/or reviewers list.
set_pr_draft_state	Mark a PR as draft or ready for review.
resolve_pr_comment	Mark a PR comment resolved or unresolved.

All tools accept optional workspace and repo. When you run the server from inside a git checkout, those are inferred from the origin remote. PR-scoped tools accept an optional pr_id; when omitted, the server resolves it by listing open PRs whose source branch matches the current checked-out branch.

Setup

Requires Node 22+.

Solo (you create your own OAuth consumer)

npx -y @mcpkits/bitbucket setup

The wizard:

1. Opens your browser to your workspace's OAuth consumers page; you create a private consumer with the listed scopes and paste back its key + secret.
2. Opens the browser again to authorize; you click Grant access.
3. Detects claude on PATH and offers to register the server with Claude Code automatically (user scope).

Restart Claude Code (or open a new session) and you're done.

Team (shared OAuth consumer)

If your team already keeps a Bitbucket OAuth consumer in your password manager, pass the key and secret as env vars and setup will skip the consumer-creation step:

BITBUCKET_CLIENT_KEY=... \
BITBUCKET_CLIENT_SECRET=... \
npx -y @mcpkits/bitbucket setup

You'll be prompted to confirm before the env vars are used.

Migrating from a previous local-build install

Just run npx -y @mcpkits/bitbucket setup. It detects an existing local-dist registration in ~/.claude.json, skips OAuth (your tokens in ~/.config/bitbucket-mcp/config.json are reused), and rewrites the registration to use npx. No re-auth needed.

Other MCP hosts (Claude Desktop, Cursor, etc.)

Add this to your host's MCP config:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@mcpkits/bitbucket"]
    }
  }
}

For the OAuth credentials and tokens, run npx -y @mcpkits/bitbucket setup once first; they're stored in ~/.config/bitbucket-mcp/config.json and used by every invocation regardless of host.

Config file

Stored at $XDG_CONFIG_HOME/bitbucket-mcp/config.json if XDG_CONFIG_HOME is set, otherwise ~/.config/bitbucket-mcp/config.json. Mode 0600; parent dir mode 0700.

{
  "clientKey": "...",
  "clientSecret": "...",
  "tokens": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresAt": 1712345678000,
    "scopes": ["account", "repository", "pullrequest", "pullrequest:write", "pipeline"]
  }
}

Never commit this file. Never share it.

Usage

Once registered and loaded, ask the agent things like:

• "Summarize PR 42 in this repo."
• "What did my latest pipeline fail on?" → the model calls get_pr_pipeline_status, then get_pipeline_step_log on the failing step.
• "Leave a comment on line 17 of src/foo.ts in PR 42 saying 'this needs a null check'." → the model calls add_pr_inline_comment.

If you're inside a git checkout of the Bitbucket repo, you typically don't need to pass workspace, repo, or pr_id — the server infers them.

Build

End users don't need to clone or build — install via npx -y @mcpkits/bitbucket setup. This section is for contributors.

Requires Node 22+ and Vite+ (vp).

vp install      # install deps
vp check        # lint + typecheck
vp test         # run tests
vp pack         # bundle to dist/bitbucket-mcp.mjs

The build produces a single executable file at dist/bitbucket-mcp.mjs with a #!/usr/bin/env node shebang and the executable bit set.

Subcommands

• bitbucket-mcp (no args) / serve — run the MCP server over stdio.
• setup — interactive wizard. Detects existing OAuth tokens and Claude Code registration to choose between fresh install, migration, or re-registration. Honors BITBUCKET_CLIENT_KEY + BITBUCKET_CLIENT_SECRET env vars for team-shared OAuth consumers (asks before using).
• credentials --key <KEY> — non-interactive: read the secret from stdin (or $BITBUCKET_CLIENT_SECRET), persist both to the config file.
• authorize — run the OAuth flow using stored credentials; open browser, wait for callback, persist tokens.
• print-config — emit the JSON payload for claude mcp add-json bitbucket --scope user.
• help — show usage.

Security notes

• OAuth tokens and consumer secret live in a 0600 file in your home directory. No env vars, no shell history.
• The OAuth callback listener binds only to 127.0.0.1. The state parameter is a 32-byte cryptographic random and compared in constant time.
• Tokens are refreshed transparently. If a refresh fails (e.g. the consumer was revoked), the MCP clears the tokens and asks you to re-run npx -y @mcpkits/bitbucket setup.
• This is a Bitbucket Cloud client — Bitbucket Server / Data Center is not supported.

License

MIT