Bitbucket MCP Server

Read-only MCP server for Bitbucket Cloud — lets Claude and other LLM clients browse repositories, source files, commits, pull requests, comments, tasks, branches, tags, CI statuses, pipelines, deployments, projects, and workspaces. Token-sparse output, no write access, credential never leaves the client layer.

Quickstart

You need a Bitbucket Cloud (Atlassian) API token with repository read scopes (read:repository:bitbucket, plus read:pullrequest:bitbucket for PRs/comments/tasks) — no write scopes. Mint one at https://id.atlassian.com/manage-profile/security/api-tokens, then add to your MCP client (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@bobmaertz/bitbucket-mcp"],
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_EMAIL": "you@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token"
      }
    }
  }
}

Then ask: "List the open PRs in acme/widgets" · "Show the comments on PR #42".

Related MCP server: Atlassian Bitbucket MCP Server

Configuration

Environment variables. LOG_LEVEL (default info) and BITBUCKET_ALLOW_WRITES (reserved, off) are optional. See .env.example.

Auth is resolved in precedence order: an access token (Bearer) wins, then the API-token pair (Basic), then the deprecated app-password pair (Basic). Supplying BITBUCKET_ACCESS_TOKEN is recommended for shared/automated use — workspace, project, and repository Access Tokens get Bitbucket's scaled rate limits (up to 10,000 req/hr vs 1,000 for a user API token). The server also surfaces a warning to stderr when Bitbucket signals the quota is nearly exhausted (X-RateLimit-NearLimit).

Tools

Read-only. workspace defaults to BITBUCKET_WORKSPACE; repo-scoped tools require repo.

bitbucket_list_repositories needs no args: omit workspace to list the configured BITBUCKET_WORKSPACE, or pass workspace to scope to another. There is no cross-workspace listing — Atlassian retired both GET /repositories and GET /workspaces under CHANGE-2770.

bitbucket_list_user_pull_requests lists all pull requests authored by a user across a whole workspace in one aggregated call — no more listing every repo and querying each. It auto-follows pagination (up to max_pages, default 10) and sorts newest-updated first (-updated_on). Omit user for the authenticated account ("my" PRs); otherwise user may be an account UUID ({…}), an Atlassian account_id, or a natural display name / nickname — the latter is resolved against the workspace's members and must match exactly one of them. It covers authored PRs only; reviewer-only involvement isn't included. Backed by GET /workspaces/{workspace}/pullrequests/{selected_user}.

bitbucket_whois goes the other way — hand it one or many account UUIDs / account_ids (as users, a single string or an array) and it returns each one's natural name (display_name, nickname) plus both ids, resolved via the workspace's members. Unknown ids come back as { query, error } rather than failing the batch, so an author UUID seen in a PR listing can always be turned back into a human name. IDs only here; to look someone up by name, pass the name straight to bitbucket_list_user_pull_requests. Backed by GET /workspaces/{workspace}/members/{member}.

bitbucket_get_pr_diff scopes the diff server-side: pass path (one or more files) and/or context (lines around each hunk) to fetch just what you need instead of downloading the whole diff and trimming it.

The source and commit tools give an agent eyes on the repository. bitbucket_list_directory and bitbucket_get_file default commit to the repo's main branch (and echo the resolved ref), so you can browse without knowing the default branch; use max_depth to pull a recursive tree in one call. bitbucket_get_file caps content by max_bytes/max_lines and returns binary: true (no content) for binary files. For "what changed", prefer bitbucket_get_diffstat (a cheap per-file summary) before pulling bitbucket_get_commit_diff, which supports the same path/context scoping as the PR diff.

For CI, bitbucket_list_pr_statuses and bitbucket_list_commit_statuses surface build/check results from any reporting system (not just Bitbucket Pipelines), and bitbucket_get_test_reports turns a failed pipeline step into a summary of pass/fail counts plus the named failing tests and their failure reasons — no log grepping. bitbucket_get_pr_activity gives a normalized timeline of updates, approvals, change requests, and comments, and bitbucket_list_commit_pull_requests answers "which PR introduced this commit?".

For discovery and governance, bitbucket_list_workspaces finds the workspace IDs you can pass elsewhere, bitbucket_list_projects / bitbucket_get_project and bitbucket_list_workspace_members cover project and membership metadata, bitbucket_list_deployments / bitbucket_list_environments give release visibility, and bitbucket_get_branching_model reports the repo's development/production branch conventions.

Efficiency

Every list/get request asks Bitbucket for a partial response (fields=) matching exactly what the presenter keeps, so the payload is trimmed at the source rather than after download. Step logs are tailed with an HTTP Range request (only the last window of bytes is transferred unless you grep, which scans the whole log). Combined with per-request field selection and q/sort filtering, this keeps both token usage and API round-trips low — important against Bitbucket's hourly rate limits.

Development

Monorepo: bitbucket-api (REST client) → bitbucket-core (config, presenters, operations) → bitbucket-mcp-server (MCP adapter).

npm install && npm run build
npm test                 # unit + hermetic HTTP integration
npm run test:contract    # validate against the vendored Bitbucket OpenAPI spec

API audit and roadmap: docs/API_AUDIT_AND_ROADMAP.md.

License

MIT