bitbucket-mcp

An MCP server for reviewing Bitbucket Cloud pull requests. Claude Code, Cursor, or any other MCP client can read a pull request, the ticket behind it, and the comments already on it, then leave review comments, without you leaving the editor.

It is deliberately small, and it cannot change your repository. There is no tool to merge, approve, decline, push, delete a branch, or run a pipeline, so the token it asks for is two read scopes. An agent using it can read code and write comments. That is all it can do.

Authentication uses Atlassian API tokens, which replaced app passwords on 28 July 2026.

Install

Needs Node 20 or newer.

git clone https://github.com/EnesPolovina/bitbucket-mcp
cd bitbucket-mcp
npm install
npm run build
cp .env.example .env     # then fill it in, see Credentials below

.env is gitignored, so it does not travel with the clone. It is the one thing you set up per machine. The tokens themselves belong to your Atlassian account, not to a machine, so the same ones work everywhere.

Check it before wiring it into a client:

./smoke.sh                 # lists open pull requests
./smoke.sh 42              # and fetches the diff for one

The server reads .env only through smoke.sh. When a client launches it, the values come from that client's config instead, so put them in both places.

Credentials

Go to https://id.atlassian.com/manage-profile/security/api-tokens and use Create API token with scopes, then pick Bitbucket. The plain Create API token button produces a token with no scopes, and the Bitbucket REST API answers those with a 401 and an empty body.

Two scopes, both read-only:

Scope	Covers
read:repository:bitbucket	Reading the repository and its diffs
read:pullrequest:bitbucket	Listing pull requests, and commenting on them

Commenting sits under the read scope, so the server never needs write access. It cannot push, merge, approve, or delete anything. Add read:pipeline:bitbucket if you want to be ready for pipeline support later.

Then set:

export ATLASSIAN_EMAIL="you@company.com"     # your Atlassian account email
export BITBUCKET_API_TOKEN="..."

The email is the one listed under Email aliases in Bitbucket personal settings, not your Bitbucket username.

Connect it

Claude Code:

claude mcp add bitbucket -- node /absolute/path/to/bitbucket-mcp/dist/index.js

Or add it to your client's config file directly:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
      "env": {
        "ATLASSIAN_EMAIL": "you@company.com",
        "BITBUCKET_API_TOKEN": "..."
      }
    }
  }
}

Tools

Tool	What it does
list_pull_requests	Lists PRs, filtered by state, author, and branch
get_pull_request	Title, description, author, state, branches
get_diffstat	Which files changed and by how much, without the diff
get_diff	The unified diff, truncated past max_chars
get_file	A whole file at the PR's commit, for the context a diff omits
get_comments	Existing comments, with the file and line for inline ones
post_comment	Posts a comment, optionally pinned to a file and line
get_jira_issue	The ticket, its links and its comments. Only if Jira is configured

They take workspace and repo_slug. If you work in one repository, set BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG alongside the credentials and drop them from the calls.

get_comments is what keeps a review from restating what a colleague already wrote three days ago, which is the fastest way to make an automated reviewer annoying.

Filtering matters more than it sounds. A page from Bitbucket holds 50 pull requests, and a long-lived repository has thousands, so an unfiltered list is mostly noise from other teams. list_pull_requests filters server-side and follows pages until it has limit results:

Argument	Match	Example
state	exact, defaults to OPEN	MERGED
author	exact account nickname	Ada Lovelace
destination_branch	exact	main, release/2.4
source_branch	substring	PROJ matches fix/PROJ-142
limit	up to 200, defaults to 50	120

Jira, optional

A diff tells you what changed. It cannot tell you whether that was what somebody asked for. Set these two and get_jira_issue appears, carrying the ticket, its linked issues and its comments:

export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_API_TOKEN="..."

It needs its own token. A Bitbucket-scoped token cannot read Jira; it answers 401. ATLASSIAN_EMAIL is shared between the two.

Scopes: read:jira-work and read:jira-user, or their granular equivalents read:issue:jira, read:comment:jira, read:user:jira. The user scope is what puts a name on each comment.

Give it your ordinary site URL. Atlassian's two kinds of token want different hosts — a classic token authenticates against the site, a scoped one answers 401 there and has to go through a gateway addressed by cloud id. The server tries the site, and on a 401 looks the cloud id up and retries, so either kind of token works without you finding that id.

Leave them unset and the tool is never registered. A tool that is present but cannot authenticate is worse than an absent one, because the model finds it, calls it, and fails halfway through a task.

The comments matter as much as the description. A ticket that was reopened, or that carries a "this broke again in production" thread, means something different from its original text.

Prompt

review_pull_request reads the ticket and the existing comments, pulls the diff, and works through a checklist: correctness, edge cases, error handling, security, test coverage, and scope creep. Findings come back worst first, each with a file, a line, and the smallest fix.

The checklist that ships here is a starting point. The one worth having is specific to your codebase, and those specifics are usually the part you cannot publish. Keep it in a file outside this repository:

export REVIEW_CHECKLIST_PATH="$HOME/.config/review-checklist.md"

Its contents replace the default. If the file is missing or empty the server logs that to stderr and falls back, so a bad path degrades the review instead of breaking it.

Write down failure modes, not incidents. "Anything writing to an audit trail has to be idempotent" is a lesson you can share. The outage that taught it to you usually is not.

Tests

npm test

No framework and no network. They cover the parts that can break quietly: a quote inside a filter cannot escape the query it is built into, the Jira tool is absent unless Jira is configured, the checklist falls back when its file is missing, and no registered tool can write to a repository.

What this does not do

MCP exposes capabilities that an agent may choose to call. It cannot gate a commit or force anyone through the checklist. If you want review standards enforced rather than offered, that belongs in a git hook or in CI, with this server alongside it.

Not included yet

get_pipeline_status, and reading a pull request's approval state.

Licence

MIT