bitbucket-mcp

English · Português (BR)

MCP server for Bitbucket Cloud, focused on the first pass of pull-request review. stdio transport, for use with Claude Code or Claude Desktop.

Why an API token (and not an app password)

Bitbucket Cloud app passwords have been in brownout since 2026-06-09 and are removed on 2026-07-28. This server uses an API token, and the HTTP Basic pair is email:token — the Bitbucket REST API requires the Atlassian account email, not the username. Using the username results in a silent 401.

1. Create the API token

1. Bitbucket top bar → Settings → Atlassian account settings → Security.
2. Create and manage API tokens → Create API token with scopes.
3. Name it, set an expiry, and select Bitbucket as the app.
4. Minimum scopes for PR review:
   • read:repository:bitbucket (read repositories, diffs, files)
   • read:pullrequest:bitbucket (read PRs and comments)
   • write:pullrequest:bitbucket (comment, approve, request changes)
5. Copy the token (shown only once).

2. Install and build

npm install
npm run build

This generates dist/index.js (the server binary).

3. Configure in Claude Code

Add this to the project's .mcp.json (or to your global Claude Code config):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_EMAIL": "your-email@domain.com",
        "BITBUCKET_API_TOKEN": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

Alternative, via the CLI:

claude mcp add bitbucket \
  -e BITBUCKET_EMAIL=your-email@domain.com \
  -e BITBUCKET_API_TOKEN=your_api_token \
  -e BITBUCKET_WORKSPACE=your_workspace \
  -- node /absolute/path/to/bitbucket-mcp/dist/index.js

BITBUCKET_WORKSPACE is optional; if omitted, each tool must be given workspace explicitly.

Tools

Read (no side effects):

Tool	Purpose
list_repositories	Repositories in the workspace
list_pull_requests	PRs by state (OPEN/MERGED/DECLINED/SUPERSEDED)
get_pull_request	PR metadata (description, branches, reviewers, approvals)
get_pull_request_diff	Unified diff — the basis for the review
get_pull_request_comments	Existing comments (general and inline)
get_pull_request_commits	PR commits
list_directory	Lists the repo file tree at a commit/branch (explore the project)
get_file	Contents of a file (default branch if commit is omitted)

Write (mutate state in Bitbucket):

Tool	Purpose
add_pull_request_comment	Comment on the PR; path + line together = inline
approve_pull_request	Approve the PR
request_changes_pull_request	Mark "request changes"

Security note

The token grants read/write access to the workspace's PRs. Treat it as a secret: keep it in an environment variable / secret manager, and never commit it. For a first-pass subagent that only suggests review without mutating anything, use a read-only scoped token — that way approve/comment fail on permission rather than relying on prompt discipline.

License

MIT © José Danilo