bucket-mcp
An MCP server for Bitbucket Cloud that lets AI agents browse code and manage pull requests, with permission modes (readonly/draft/readwrite) enforced by the server.
Repositories: list and inspect repos in a workspace.
Pull requests: list, view, create drafts, comment (pending), add checklist tasks, view diffs/diffstats, check CI statuses, and check merge status.
Commits: list commits, view commit details, diffs, diffstats, and CI statuses.
Branches & tags: list branches and tags, including BBQL filtering.
Code search: search code across a workspace's repositories.
Source browsing: read file contents or list directories at any revision; metadata-only option for large files.
Workspace & user discovery: list workspaces, list workspace members (resolve UUIDs for reviewers), list a user's PRs, and identify the authenticated account.
Write operations (depending on mode): create draft PRs, pending comments/tasks; in readwrite mode also merge/decline/delete and create live PRs/comments.
Provides tools for interacting with Bitbucket Cloud, enabling code review and pull request workflows, repository management, commits, branches, file browsing, code search, and workspace/user discovery.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bucket-mcp what pull requests are awaiting my review?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bucket-mcp
An MCP server for Bitbucket Cloud — code review and PR workflows (repos, pull requests, commits, branches, file browsing, code search, workspace/user discovery) for Claude Code, Codex, Cursor, and any other MCP-capable agent.
Setup
npx bucket-mcp configureOne guided command: creates and validates a Bitbucket API token (a scope guide helps you pick what to check), sets a default workspace and permission mode, then registers with whichever agent you choose. Registration is automatic for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Pi Agent — "my agent isn't listed" just prints a config block to paste in yourself. Restart your agent afterward and the tools are available.
Prefer to do it by hand, or want to see exactly what gets registered? See Manual setup below.
Run it again any time to change your token, default workspace, or permission mode. It shows what you're currently configured as, pre-fills every question with that, and lets you keep your existing token instead of pasting it again — then replaces the old registration with the new one rather than erroring on a name collision.
Related MCP server: Bitbucket MCP
Uninstalling
npx bucket-mcp uninstallScans every agent configure can register with (plus any "always ask" permission rules it wrote — see below), shows what it found, and removes it after one confirmation. No need to remember which agent you used.
Permission modes
Set via BITBUCKET_MCP_MODE, or picked during configure:
Mode | What it allows |
| No write or destructive tool of any kind. |
| Can create draft PRs and pending comments/tasks — nothing else that writes. A draft PR is visible to teammates, just marked not-ready-for-review; a pending comment/task is invisible to everyone but its author until they submit their review in Bitbucket's own UI. Either way, a human still has to mark it ready or submit it in Bitbucket before anyone else can act on it — this mode can't do that step. |
| Full access, including merge/decline/delete. PRs and comments/tasks you create still default to draft/pending — pass |
BITBUCKET_MCP_READONLY=1 still works as an alias for mode=readonly, for anyone who set it before BITBUCKET_MCP_MODE existed.
Always-ask enforcement for write operations
Modes above are enforced by this server — they control what's even possible. Some agents let you add a second, independent layer on top: a host-level rule that always pauses for your approval before running one of this server's write operations, even if that agent is otherwise running in an auto-approve/"yolo" mode.
configure offers this automatically, right after registering, for the three agents whose own docs confirm the rule actually survives their most permissive mode: Claude Code, OpenCode, and Pi Agent. Say yes and it writes the rule for you — no manual editing.
It isn't offered for Cursor or GitHub Copilot: Cursor's mechanism is an allowlist only ("best-effort, not a security guarantee" per its own docs), and Copilot's permission model has no "always ask" tier, just allow/deny. For Codex CLI, no action is needed — it already inspects each tool's own risk annotation and always asks before bitbucket_pull_request_merge, bitbucket_pull_request_decline, or bitbucket_branch_delete, regardless of its approval policy.
Token scopes by use case
On the "Select Bitbucket scopes" screen, search each name below and check it:
Use case | Scopes to check |
Read-only |
|
Draft (default) / Read-write | everything above, plus |
Draft and Read-write need the same token scopes — Bitbucket has no separate scope for "write, but only drafts." The difference between those two modes is enforced by BITBUCKET_MCP_MODE itself, not the token: a write-scoped token used in draft mode still can't merge or approve anything, because those tools aren't registered in that mode.
Rotating your token
Bitbucket API tokens expire (max 1 year) and can't be edited after creation — only replaced. Re-run configure with the new token, or update the BITBUCKET_API_TOKEN value directly in Claude Code's MCP config, then restart Claude Code.
Updating
Restart Claude Code — npx re-resolves bucket-mcp's latest published version each launch. This only picks up an actual release, not every commit to main; check npm if you're not sure whether the fix you want has shipped yet.
Troubleshooting
A tool call fails with "this operation requires scope(s) [...]" — your token doesn't have that scope. Create a new one with it added and re-run
configure.Tools you expect are missing from the list — check your
BITBUCKET_MCP_MODE, and check your token's scopes."No workspace specified..." error — either pass
workspaceexplicitly, setBITBUCKET_DEFAULT_WORKSPACE, or ask the AI to callbitbucket_workspace_listfirst.
Manual setup (Claude Code)
Setting up a different agent by hand? Run configure, answer the prompts, and pick "My agent isn't listed" at the end — it prints the same standard MCP config block without registering anything for you.
1. Get a Bitbucket API token
Bitbucket → avatar → Account settings → Security → Create and manage API tokens
Click Create API token with scopes (not the plain Create API token button)
Name it, set expiry to a few months out (not the max), then Next
Pick Bitbucket, then Next
Check the scopes — see Token scopes by use case
Create token — copy it now, you won't see it again
2. Set the token without putting it in your shell history
# in ~/.zshrc, ~/.bashrc, or a git-ignored .env you source
export BITBUCKET_API_TOKEN=your-token-hereThe server reads it from the environment it's launched in, so it never needs to appear on the claude mcp add command line or get written into Claude Code's own config file.
3. Add it to Claude Code
claude mcp add --scope user --transport stdio bitbucket -- npx -y bucket-mcp--scope user registers it globally across every project rather than just the one you happen to be in. npx fetches the published package and runs it, no local clone or build step needed.
Optional: a default workspace
Most people work in one Bitbucket workspace. Set one and every tool's workspace argument becomes optional:
export BITBUCKET_DEFAULT_WORKSPACE=your-team-slugYou can still target a different workspace any time by asking for it explicitly — the AI can call bitbucket_workspace_list to discover what else it has access to.
Optional: permission mode
export BITBUCKET_MCP_MODE=readonly # or draft (the default), or readwriteSee Permission modes above for what each one allows.
Development
git clone git@github.com:Stan15/bucket-mcp.git
cd bucket-mcp
npm install && npm run build
npm testPoint the manual setup's step 3 command at node /absolute/path/to/bucket-mcp/dist/index.js instead of the npx line to run from your local clone.
Available Tools
26 toolsbitbucket_branch_listBRead-onlyIdempotent
List branches in a repository.
Inputs: repoSlug (required), query, maxItems, workspace.
bitbucket_code_searchBRead-onlyIdempotent
Search code across a workspace's repositories.
Inputs: searchQuery (required), maxItems, workspace.
bitbucket_commit_diffARead-onlyIdempotent
Get the full unified diff for a commit or commit range, optionally scoped to one file. Prefer diffstat first.
Inputs: spec (required), repoSlug (required), path, workspace.
bitbucket_commit_diffstatARead-onlyIdempotent
Get the per-file change summary for a commit or commit range (e.g. 'base..head'). Prefer over the full diff unless file contents are actually needed.
Inputs: spec (required), repoSlug (required), workspace.
bitbucket_commit_getCRead-onlyIdempotent
Get one commit's details.
Inputs: commit (required), repoSlug (required), workspace.
bitbucket_commit_listBRead-onlyIdempotent
List commits on a branch/ref.
Inputs: repoSlug (required), maxItems, revision, workspace.
bitbucket_commit_list_statusesCRead-onlyIdempotent
List build/CI statuses attached to a commit.
Inputs: commit (required), repoSlug (required), workspace.
bitbucket_pull_request_comment_createA
Add a comment to a pull request as pending - invisible to everyone but you until you submit your review in Bitbucket's own UI.
Inputs: id (required), body (required), repoSlug (required), workspace, +2 more.
bitbucket_pull_request_comment_listBRead-onlyIdempotent
List comments on a pull request.
Inputs: id (required), repoSlug (required), maxItems, workspace.
bitbucket_pull_request_createA
Create a new pull request as a draft - visible to teammates, but marked not-yet-ready-for-review until someone marks it ready in Bitbucket.
Inputs: title (required), repoSlug (required), sourceBranch (required), reviewers, +3 more.
bitbucket_pull_request_diffARead-onlyIdempotent
Get the full unified diff for a pull request, optionally scoped to one file. Prefer diffstat first; use this only when file contents are actually needed.
Inputs: id (required), repoSlug (required), path, workspace.
bitbucket_pull_request_diffstatARead-onlyIdempotent
Get the per-file change summary (files touched, lines +/-) for a pull request. Cheapest way to see 'what changed' - prefer this over the full diff unless file contents are actually needed.
Inputs: id (required), repoSlug (required), workspace.
bitbucket_pull_request_getARead-onlyIdempotent
Get full details of one pull request.
Inputs: id (required), repoSlug (required), workspace.
bitbucket_pull_request_listBRead-onlyIdempotent
List pull requests in a repository, optionally filtered by state.
Inputs: repoSlug (required), state, maxItems, workspace.
bitbucket_pull_request_list_by_userARead-onlyIdempotent
List a user's pull requests across every repository in a workspace - use bitbucket_whoami first to list your own.
Inputs: selectedUser (required), state, maxItems, workspace.
bitbucket_pull_request_list_statusesARead-onlyIdempotent
List build/CI statuses on a pull request's current head commit - use to check whether a PR is safe to merge.
Inputs: id (required), repoSlug (required), workspace.
bitbucket_pull_request_merge_statusARead-onlyIdempotent
Check the status of a merge that bitbucket_pull_request_merge reported as still in progress.
Inputs: id (required), taskId (required), repoSlug (required), workspace.
bitbucket_pull_request_task_createA
Add a checklist task to a pull request as pending - invisible to everyone but you until you submit your review in Bitbucket's own UI.
Inputs: id (required), content (required), repoSlug (required), workspace.
bitbucket_pull_request_task_listARead-onlyIdempotent
List a pull request's checklist tasks (what PullRequestSchema.task_count counts) - distinct from comments.
Inputs: id (required), repoSlug (required), workspace.
bitbucket_repository_getBRead-onlyIdempotent
Get details of one repository.
Inputs: repoSlug (required), workspace.
bitbucket_repository_listBRead-onlyIdempotent
List repositories in a workspace.
Inputs: query, maxItems, workspace.
bitbucket_source_getARead-onlyIdempotent
Read a file's contents or list a directory at a given revision. Omit path (or use "") for the repository root. Set metaOnly: true to check a file's size/type without fetching its full contents - do this first for anything that might be large.
Inputs: repoSlug (required), revision (required), path, metaOnly, +1 more.
bitbucket_tag_listCRead-onlyIdempotent
List tags in a repository.
Inputs: repoSlug (required), maxItems, workspace.
bitbucket_whoamiARead-onlyIdempotent
Get the identity (display name, uuid) of the currently authenticated Bitbucket account.
Inputs: no named parameters.
bitbucket_workspace_listARead-onlyIdempotent
List every Bitbucket workspace the authenticated account can access. Use this to discover a workspace slug before calling any other tool, or to find one other than the configured default.
Inputs: maxItems.
bitbucket_workspace_member_listARead-onlyIdempotent
List members of a workspace, with their account uuid. Use this to resolve a teammate's name to the uuid bitbucket_pull_request_create's reviewers argument requires (it does not accept plain names).
Inputs: maxItems, workspace.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Tools are organized by resource, and the diff/diffstat split is clearly explained, so the most similar pairs remain distinguishable. A few overlaps like PR-level vs commit-level statuses could cause an agent to pick the wrong variant, but the descriptions generally prevent real ambiguity.
The bitbucket_<resource>_<action> pattern is used consistently, giving the set a uniform and predictable shape. Minor outliers like bitbucket_whoami and bare-noun operations such as diffstat or merge_status keep it from being a perfect pattern.
With 26 tools, the surface crosses the 25-tool threshold and includes several near-duplicate pairs for diff/diffstat and statuses. A more curated set would be easier to navigate, especially since one tool, merge_status, lacks its corresponding merge action.
The pull request workflow is incomplete: merge_status references a merge tool that is not present, and pull_request_create only creates drafts with no way to mark them ready, update, or merge. Repositories, branches, and tags are also read-only, leaving common lifecycle actions out of reach.
Maintenance
Related MCP Connectors
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables AI assistants to interact with Bitbucket Cloud and self-hosted instances for pull request reviews, code search, repository operations, and managing PR comments and approvals.19GPL 3.0
- AlicenseAqualityDmaintenanceConnects Claude Desktop and Claude Code to Bitbucket Cloud, enabling searching PRs, commits, diffs, and file content for AI-assisted bug triage and impact analysis.840 npmISC
- AlicenseNot gradedqualityCmaintenanceEnables pull-request review workflows on Bitbucket Cloud via Claude Code, offering tools to view PR metadata, comments, diffs, and to post comments or approve.6,189 npmMIT
- FlicenseBqualityBmaintenanceEnables interaction with Bitbucket Cloud pull requests, comments, diffs, and pipelines from the terminal via Claude Code.21-