Bitbucket MCP Server: Setup & PR Workflows (2026 Guide)

TL;DR + what you actually need

• One package: @aashari/mcp-server-atlassian-bitbucket — the most-installed community implementation. Runs via npx, needs Node 18+, and covers Bitbucket Cloud only (not Server/Data Center).
• Two env vars: ATLASSIAN_USER_EMAIL and ATLASSIAN_API_TOKEN — a scoped API token created at id.atlassian.com with the repository, workspace, and (for PR writes) pullrequest scopes. Do not set this up with an app password: Atlassian started browning them out on June 9, 2026 and removes them on July 28, 2026.
• Six tools: bb_get, bb_post, bb_put, bb_patch, bb_delete, bb_clone — generic REST passthrough to any Bitbucket Cloud 2.0 endpoint, with JMESPath filtering and a token-efficient default output format.

The copy-paste, if that’s all you came for:

claude mcp add bitbucket \
  -e [email protected] \
  -e ATLASSIAN_API_TOKEN=your_scoped_token \
  -- npx -y @aashari/mcp-server-atlassian-bitbucket

The rest of this guide explains why the auth looks like that, how the official Atlassian MCP server fits, and where the sharp edges are.

What Bitbucket MCP actually does

The Bitbucket MCP server is a stdio process — your MCP client launches it as a subprocess — that translates tool calls from the model into authenticated requests against Bitbucket Cloud’s REST API 2.0. Ask “show me the open pull requests that need my review” and the agent calls bb_get with /repositories/your-workspace/your-repo/pullrequests and a state filter, gets real JSON back, and answers from data instead of guessing.

The design choice that defines this server: instead of shipping one named tool per operation, version 2.x ships six generic tools mapped to HTTP verbs. Any endpoint Bitbucket exposes — pull requests, branches, commits, file contents, pipelines, deployments, issues — is reachable by passing the right path. The server prepends the /2.0 API prefix automatically, supports server-side query parameters, and lets the agent attach a JMESPath expression (passed as jq) to strip the response down to the fields it needs.

Two consequences worth internalizing before you install. First, the tool list costs very little context — six tool schemas instead of thirty. Second, correctness now depends on the model knowing Bitbucket’s REST paths. Claude knows this API well, and the tool descriptions include the common paths, but you’ll occasionally see an invented endpoint return a 404 — more on that in limits.

The server also ships a CLI mode (same commands, terminal output) which is the fastest way to verify your credentials before blaming your MCP client:

export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_scoped_token"

npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"

If that prints your workspaces, the MCP side will work. If it doesn’t, fix auth first.

The Bitbucket MCP landscape: community vs official

“Bitbucket MCP” is not one thing. Three implementations matter in 2026, and the differences are sharper than most roundups admit.

Does Atlassian’s official MCP server cover Bitbucket?

Yes — but with enough caveats that the answer is effectively “not for most individual developers.” Atlassian’s remote MCP server (now branded the Rovo MCP Server, endpoint https://mcp.atlassian.com/v1/mcp/authv2) launched around Jira and Confluence, and its getting-started docs still headline Jira, Confluence, and Compass. Bitbucket Cloud tools were added to the supported-tools list — read tools for workspaces, repos, PRs, pipelines, and deployments, plus write tools for PR create/approve/merge — but Atlassian’s own documentation attaches three conditions: Bitbucket tools work over API-token authentication only (not the OAuth 2.1 browser flow), they must be enabled by your organization admin, and your Bitbucket workspace must be linked to an Atlassian organization.

In practice: if you’re on a team whose admin has wired all of that up, the official remote server is a reasonable zero-install path — especially if you already use it for Jira and Confluence. If you’re an individual developer with a Bitbucket workspace and an API token, the community server works today with no admin in the loop, which is why it remains the default install. One migration note if you adopted the official server early: Atlassian is retiring the original mcp.atlassian.com/v1/sse endpoint after June 30, 2026 — switch configs to the /v1/mcp/authv2 URL.

When the second community server is the right pick

The aashari server is Cloud-only by design. If your company runs self-hosted Bitbucket Server or Data Center, use pdogra1299’s bitbucket-mcp-server (npm: @nexus2520/bitbucket-mcp-server) instead. It takes the opposite design position — 29 named tools like get_pull_request_diff and set_pr_approval, grouped and filterable via BITBUCKET_TOOL_GROUPS to control context cost — and supports both Cloud and Server, including server-only features like PR tasks and index-backed code search. Both implementations are catalogued on our /servers/bitbucket page.

Auth: scoped API token, not app password (this changed in June 2026)

This is the section most likely to fix your broken setup. Bitbucket historically used app passwords — per-user secondary passwords with permission checkboxes — and nearly every Bitbucket MCP tutorial from 2025 tells you to create one. That advice is now actively harmful. Atlassian’s deprecation timeline:

• September 9, 2025 — creating new app passwords disabled.
• June 9 – July 27, 2026 — controlled brownouts: existing app passwords intermittently rejected. (If your MCP server worked last week and fails intermittently this week, this is the cause.)
• July 28, 2026 — app passwords removed entirely.

The replacement is the scoped API token, and the aashari server supports it as the recommended path:

1. Go to id.atlassian.com → Security → API tokens.
2. Click “Create API token with scopes” — the scoped variant, not the classic unscoped token.
3. Select Bitbucket as the product.
4. Pick scopes: repository + workspace for read-only; add pullrequest if the agent should create, comment on, approve, or merge PRs.
5. Copy the token (it starts with ATATT) and pair it with your Atlassian account email.

The env block the server expects:

[email protected]
ATLASSIAN_API_TOKEN=ATATT...        # scoped API token
BITBUCKET_DEFAULT_WORKSPACE=acme    # optional but saves tokens

Two details that prevent most auth tickets. The username for token auth is your Atlassian account email, not your Bitbucket username — mixing those up is the classic 401. And scope choice is your real permission boundary: an agent holding a read-only token can call bb_post all it likes; Bitbucket returns 403 and nothing changes. Issue separate tokens per agent and per write level, and rotate them like any other production secret — they ride as plain basic auth on every request.

Install (every client)

The community server is stdio-only — there’s no hosted endpoint to point at. Every install path runs npx -y @aashari/mcp-server-atlassian-bitbucket as a subprocess with the env vars above. The install panel below pulls its config snippets from the canonical /servers/bitbucket catalog entry, so it stays in sync as the package evolves:

One-line install · Bitbucket

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes:

• Claude Code: the one-liner from the TL;DR. Add --scope project to register it in the repo’s .mcp.json for your whole team — but then keep the token itself out of the file and in each user’s environment. Flag reference at /clients/claude-code.
• Claude Desktop: add the mcpServers JSON block to claude_desktop_config.json with command: "npx", args: ["-y", "@aashari/mcp-server-atlassian-bitbucket"], and the two env vars. Restart the app.
• Cursor: same JSON shape in ~/.cursor/mcp.json; the tools appear in the agent’s tool list after restart.
• VS Code / Windsurf: paste the panel’s JSON into the extension’s MCP config (mcp.json in workspace settings for VS Code, ~/.codeium/windsurf/mcp_config.json for Windsurf).
• System-wide: the server also reads ~/.mcp/configs.json — one place for credentials shared across clients, keyed as "bitbucket".

Codex CLI

Codex reads MCP servers from ~/.codex/config.toml:

[mcp_servers.bitbucket]
command = "npx"
args = ["-y", "@aashari/mcp-server-atlassian-bitbucket"]

[mcp_servers.bitbucket.env]
ATLASSIAN_USER_EMAIL = "[email protected]"
ATLASSIAN_API_TOKEN = "ATATT..."

Restart Codex and confirm with codex mcp list. On Windows, npx-launched servers are their own genre of failure (path escaping, cmd /c wrappers, the -32601 startup crash) — we wrote up every verified fix in the Codex MCP Windows troubleshooting guide.

Tools walkthrough

Six tools, five of them HTTP verbs. All API tools accept path (the /2.0 prefix is added for you), optional queryParams, an optional JMESPath filter (jq), and an outputFormat of toon (default) or json.

• bb_get — read anything: workspaces, repo metadata, PR lists, PR diffs, commits, branch lists, file contents, pipeline runs.
• bb_post — create: open a PR, add a comment, approve, request changes, merge, decline, trigger a pipeline.
• bb_put / bb_patch — replace or partially update resources. Note: Bitbucket’s PR-update endpoint expects PUT, so PR edits go through bb_put, not bb_patch (a recurring GitHub-issue trap).
• bb_delete — remove: stale branches, comments, approvals (a DELETE on /approve withdraws yours).
• bb_clone — clone a repository to a local path, bridging from “agent reads the API” to “agent works on the checkout.”

The paths the agent will use constantly — worth pasting into your project’s CLAUDE.md so the model never guesses:

/workspaces
/repositories/{workspace}
/repositories/{workspace}/{repo}
/repositories/{workspace}/{repo}/refs/branches
/repositories/{workspace}/{repo}/commits
/repositories/{workspace}/{repo}/src/{commit}/{filepath}
/repositories/{workspace}/{repo}/pullrequests            # GET list, POST create
/repositories/{workspace}/{repo}/pullrequests/{id}       # GET / PUT
/repositories/{workspace}/{repo}/pullrequests/{id}/diff
/repositories/{workspace}/{repo}/pullrequests/{id}/comments
/repositories/{workspace}/{repo}/pullrequests/{id}/approve
/repositories/{workspace}/{repo}/pullrequests/{id}/merge
/repositories/{workspace}/{repo}/pipelines
/repositories/{workspace}/{repo}/deployments

On output: TOON (Token-Oriented Object Notation) is a tabular format the server emits by default, cutting 30–60% of tokens vs raw JSON on list-shaped responses. Combined with a jq filter like values[*].{id: id, title: title, state: state}, a 50-PR listing collapses from tens of kilobytes of JSON to a few hundred tokens. The README’s own advice is blunt: always filter. Unfiltered Bitbucket responses are the main way this server gets expensive.

Recipes

Five workflows where the install pays for itself. Each assumes valid credentials and (ideally) a BITBUCKET_DEFAULT_WORKSPACE set.

Recipe 1 — PR review without leaving the editor

The flagship workflow. Prompt: “Pull the diff for PR #42 in acme/backend-api, read the existing review comments, and review the change: flag anything that touches auth or changes error handling. Post your findings as a single PR comment, but show me the comment text first.” The agent chains bb_get on /pullrequests/42/diff and /comments, reasons over the patch, then bb_posts the comment after you approve it. The human-preview step matters: review comments are public artefacts, and you want the model’s tone checked once before it speaks for you.

Recipe 2 — Pipeline checks before merge

Prompt: “For PR #42, check the latest pipeline run on its source branch. If anything failed, fetch the failed step and summarize the error. If it’s green and the PR has two approvals, merge with squash.” The agent reads /pipelines filtered by branch, inspects the run, then conditionally bb_posts to /merge with {"merge_strategy": "squash"}. Gate the merge behind your client’s tool-approval prompt — this is the most side-effectful call in the whole server.

Recipe 3 — Repo Q&A on code you haven’t cloned

Prompt: “In acme/payments-service, get src/config/retry.ts from main and explain how backoff is configured. Then list the last five commits that touched that file.” File reads go through /src/{commit}/{filepath}, commit history through /commits with a path filter. For one-file questions this beats cloning; for whole-subsystem questions, bb_clone into a workspace folder and let your agent grep locally instead.

Recipe 4 — Standup digest across the team

Prompt: “List open PRs across acme/backend-api, acme/frontend, and acme/infra. Group by author, flag anything open longer than five days or with zero reviewers, and give me a one-line status each.” Three bb_get calls with queryParams {"state": "OPEN", "pagelen": "20"} and a jq projection, joined in-context. This is the recipe that converts skeptical team leads.

Recipe 5 — Branch hygiene sweep

Prompt: “List branches in acme/backend-api whose latest commit is older than 90 days and that have no open PR. Show me the list; after I confirm, delete them.” Reads via /refs/branches, cross-checked against open PRs, deletions via bb_delete one branch at a time. Run it monthly; keep the confirm step forever.

Limits + what we got wrong

Honest constraints, including the ones we tripped on while testing.

• Cloud only. The canonical server authenticates against bitbucket.org. Self-hosted Server/Data Center needs the nexus2520 implementation or Atlassian’s separate DC tooling. There is no flag that makes aashari’s server talk to an internal Bitbucket — an open GitHub issue asks exactly this.
• The generic-tool tradeoff is real. Six tools keep context cheap, but the model must produce correct REST paths. We saw occasional invented endpoints (a 404 on a plausible-looking /pullrequests/{id}/files) until we pasted the path list from the tools section into the project’s instructions file. Some users preferred the pre-2.0 named tools for discoverability — the migration drew complaints in the repo’s issue tracker — so if you want named tools, that’s another reason to look at nexus2520.
• What we got wrong #1: we assumed bb_patch would update a PR title. Bitbucket’s PR endpoint wants PUT; the PATCH fails. Use bb_put on /pullrequests/{id} with the fields you’re changing.
• What we got wrong #2: we assumed bb_clone would reuse the API token transparently. Cloning is git-over-HTTPS, not the REST API, and there’s an open issue reporting 403s on bb_clone with the new scoped tokens. If you hit it, clone manually with your git credential helper and use the MCP tools for the API half.
• Rate limits are Bitbucket’s, not the server’s. Bitbucket Cloud enforces per-user hourly limits that vary by endpoint group; the server surfaces 429s verbatim. A loop-happy agent paginating a large workspace can hit them — prefer one filtered list call over fifty detail calls.
• Response size is the hidden cost. A full PR object with links and rendered fields is enormous. The combination of pagelen, Bitbucket’s fields sparse fieldsets, and jq is not optional hygiene — it’s the difference between a 500-token tool result and a 20,000-token one.

Troubleshooting

Considering GitHub or GitLab instead?

If you’re evaluating Bitbucket MCP as part of a broader “which forge plays best with agents” decision, calibrate expectations:

• GitHub: the GitHub MCP server is first-party (maintained by GitHub itself), ships a hosted remote option with OAuth, and has the largest tool surface of the three. If your code already lives on GitHub, it’s the most polished agent integration in the category.
• GitLab: the GitLab MCP servers are community-maintained (several active implementations) and cover MRs, issues, and CI in the same shape this guide covers PRs and Pipelines.
• Bitbucket: you’re in the middle — no fully open first-party server, but a mature community option plus restricted official coverage through Atlassian’s remote MCP. For teams already paying for Atlassian Cloud, that combination is entirely workable.

The agent workflows themselves transfer almost 1:1 across forges — a PR review recipe is a PR review recipe. For the broader map of what’s worth installing this year, see our awesome MCP servers roundup and the full server directory.

FAQ

Sources

• Canonical community implementation: github.com/aashari/mcp-server-atlassian-bitbucket (README: auth options, tool table, CLI commands, TOON/JMESPath guidance) and its issue tracker (bb_clone 403, bb_patch on PRs, workspace-scope and connected-status reports cited above)
• npm package: @aashari/mcp-server-atlassian-bitbucket
• Bitbucket Cloud REST API 2.0 reference: developer.atlassian.com/cloud/bitbucket/rest
• App-password deprecation timeline: Atlassian: Bitbucket Cloud transitions to API tokens and the brownout schedule notice
• Atlassian Rovo MCP Server docs: getting started and supported tools (Bitbucket tool conditions, endpoint migration date)
• Cloud + Server/DC alternative: github.com/pdogra1299/bitbucket-mcp-server
• Canonical MCP.Directory entry: /servers/bitbucket

Note on community embeds: we found no verifiable first-party X/Twitter post from the maintainer announcing this server, so this guide cites the repository, its issue tracker, and Atlassian’s documentation instead of embedding social posts.