Bitbucket MCP Server

Read-only MCP server for Bitbucket Cloud — lets Claude and other LLM clients browse repositories, pull requests, comments, tasks, and branches. 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 — auth is Basic email:token. LOG_LEVEL (default info) and BITBUCKET_ALLOW_WRITES (reserved, off) are optional. The deprecated BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD pair is accepted as a fallback. See .env.example.

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 must be an account UUID ({…}) or Atlassian account_id — bare usernames were removed by Bitbucket. It covers authored PRs only; reviewer-only involvement isn't included. Backed by GET /workspaces/{workspace}/pullrequests/{selected_user}.

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

Design notes: docs/ai/DESIGN.md.

License

MIT