bitbucket-mcp

A small local MCP server wrapping the Bitbucket Cloud API for pull-request reviews in Claude Code. Works with any workspace/repo via env vars; the workspace defaults to campsys, and you set BB_REPO per repo you review.

Tools

Tool	Type	Purpose
get_pr	read	PR metadata (title, state, branches, commit hashes)
list_comments	read	All comments (paginated), inline path/line, reply parent ids
get_diff	read	PR diff via local git diff base...head (avoids the API /diff 401)
post_comment	write	Post a comment; supports inline (path+to) and replies (parent_id)
approve	write	Approve the PR

Requirements

• Node 18+ (uses built-in fetch; developed on Node 25).
• git on PATH (used by get_diff).
• A scoped Atlassian API token — see below. The token is per-person and is never committed or shared.

1. Get your own Atlassian API token

App Passwords are being removed by Atlassian (final removal 2026-07-28), so use a scoped API token:

1. Create one at https://id.atlassian.com/manage-profile/security/api-tokens.
2. Give it these Bitbucket scopes: read:pullrequest:bitbucket, write:pullrequest:bitbucket, read:repository:bitbucket, read:account. (A plain Jira token without Bitbucket scopes returns 401.)

Set these environment variables (persist them for your user/shell):

Var	Value
BB_EMAIL	your Atlassian account email
BB_API_TOKEN	the scoped token from step 1

Windows (PowerShell, persistent):

[Environment]::SetEnvironmentVariable('BB_EMAIL','you@company.com','User')
[Environment]::SetEnvironmentVariable('BB_API_TOKEN','<token>','User')

macOS/Linux: add export BB_EMAIL=... / export BB_API_TOKEN=... to your shell profile.

2. Clone and install

git clone <REPO_URL> bitbucket-mcp
cd bitbucket-mcp
npm install

3. Register with Claude Code

Option A — user scope (recommended; available in every project):

claude mcp add bitbucket --scope user -- node /absolute/path/to/bitbucket-mcp/server.js

The server inherits BB_EMAIL/BB_API_TOKEN from your environment.

Option B — a single project: copy the bitbucket block from mcp-config.example.json into that project's .mcp.json, replacing the path. (Add .mcp.json to that repo's .gitignore if you don't want it committed.)

Restart Claude Code; approve the bitbucket server when prompted.

Configuration (env)

Var	Default	Notes
BB_EMAIL	—	required
BB_API_TOKEN	—	required
BB_REPO	—	required; repo slug being reviewed
BB_WORKSPACE	campsys	Bitbucket workspace
BB_REPO_PATH	current working dir	local checkout used by get_diff

get_diff fetches the PR source branch into refs/remotes/origin/bb-mcp-tmp and diffs three-dot against the PR's destination.commit.hash. It runs git in BB_REPO_PATH, so that must be a local clone of the repo being reviewed.

Smoke test

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node server.js

Should list the five tools.

Note on write tools

post_comment and approve mutate the PR. The intended workflow is to draft content, get explicit human approval, then call the write tool — not to post automatically.