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