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.

Related MCP server: Bitbucket MCP

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):

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

Comments

Descriptions

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