bb-mcp-server

An MCP server for Bitbucket Cloud, giving MCP clients (Claude Code, Claude Desktop, etc.) tools to read and manage pull requests, their comments, and their descriptions.

Atlassian has announced an official Bitbucket MCP server; at the time this was written it wasn't yet available, so this fills the gap with the same underlying REST API.

Features

• Pull requests — list, get, create, update, merge, decline, approve/unapprove, diff, diffstat
• Comments — list, get, create (general, inline, or as a reply), update, delete
• Descriptions — focused get/update tools that touch only the description field

See Tools below for the full list.

Requirements

• Node.js >= 18.17
• A Bitbucket Cloud account with an Atlassian API token

Setup

npm install
npm run build

Configure credentials via environment variables (see .env.example):

Variable	Required	Description
BITBUCKET_EMAIL	yes	Atlassian account email, used with the API token for Basic Auth.
BITBUCKET_API_TOKEN	yes	API token from id.atlassian.com.
BITBUCKET_WORKSPACE	no	Default workspace slug, so tools can omit workspace per call.
BITBUCKET_REPO_SLUG	no	Default repository slug, so tools can omit repoSlug per call.
BITBUCKET_BASE_URL	no	API base URL override. Defaults to https://api.bitbucket.org/2.0.

Register with an MCP client

Example for Claude Code (claude mcp add) or a client's mcp.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bb-mcp-server/dist/index.js"],
      "env": {
        "BITBUCKET_EMAIL": "you@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "my-workspace",
        "BITBUCKET_REPO_SLUG": "my-repo"
      }
    }
  }
}

BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG are optional — omit them to require every tool call to specify workspace/repoSlug explicitly, which is useful if the client should be able to work across multiple repositories.

Try it with the MCP Inspector

npm run inspector

Tools

All tools accept optional workspace / repoSlug arguments that fall back to BITBUCKET_WORKSPACE / BITBUCKET_REPO_SLUG when omitted.

Pull requests

Tool	Description
bb_list_pull_requests	List PRs, filterable by state or a Bitbucket query string.
bb_get_pull_request	Fetch full details of one PR.
bb_create_pull_request	Open a new PR.
bb_update_pull_request	Update title, description, reviewers, and/or destination.
bb_merge_pull_request	Merge an open PR.
bb_decline_pull_request	Decline an open PR.
bb_approve_pull_request	Approve a PR as the authenticated user.
bb_unapprove_pull_request	Remove the authenticated user's approval.
bb_get_pull_request_diff	Fetch the unified diff as raw text.
bb_get_pull_request_diffstat	Fetch a per-file change summary.

Comments

Tool	Description
bb_list_pull_request_comments	List all (non-deleted) comments on a PR.
bb_get_pull_request_comment	Fetch a single comment.
bb_create_pull_request_comment	Add a comment — general, inline (via inlinePath/inlineLine), or a reply (via parentId).
bb_update_pull_request_comment	Edit a comment's body.
bb_delete_pull_request_comment	Delete a comment.

Descriptions

Tool	Description
bb_get_pull_request_description	Read just a PR's description.
bb_update_pull_request_description	Replace just a PR's description, without touching other fields.

Development

npm run dev         # run the server directly with tsx (no build step)
npm run typecheck   # tsc --noEmit
npm run lint         # eslint
npm run format       # prettier --write
npm test             # vitest
npm run build         # compile to dist/

Architecture

src/
  config.ts           # env var loading/validation (zod)
  bitbucket/
    client.ts          # typed Bitbucket REST API v2.0 client (auth, pagination, errors)
    errors.ts           # BitbucketApiError
    types.ts             # Bitbucket API response shapes
  tools/
    shared.ts            # zod param helpers, workspace/repo resolution, error wrapping
    pullRequests.ts        # bb_* PR tools
    comments.ts              # bb_* comment tools
    descriptions.ts           # bb_* description tools
    index.ts                   # registerAllTools
  server.ts                     # builds the McpServer and registers tools
  index.ts                       # stdio entrypoint

Authentication notes

This server authenticates with HTTP Basic Auth using your Atlassian account email and an API token — the auth method Atlassian currently recommends for Bitbucket Cloud (app passwords are being phased out). The token only needs the Pull Requests scope for the operations this server performs.

License

MIT