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

Bitbucket top bar → Settings → Atlassian account settings → Security.
Create and manage API tokens → Create API token with scopes.
Name it, set an expiry, and select Bitbucket as the app.
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)
Copy the token (shown only once).

2. Install and build

Terminal

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):

config.json

{
  "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:

Terminal

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.

Bitbucket MCP README