mcp-bitbucket

Bitbucket Server for AI agents and the humans next to them. Read pull requests and their diffs without a clone, draft a review and publish it with a verdict, post blocking tasks, browse code and commits, open, merge or decline pull requests — from an MCP client, from a shell, or from your own TypeScript.

Bitbucket Server / Data Center only. Bitbucket Cloud is not supported.

Packages

Claude Code / Claude Desktop tool use → mcp. Terminal, scripts, CI, agents that run commands → cli. Building something else → core. They read the same credentials and install side by side.

Related MCP server: Atlassian Bitbucket MCP Server

Prerequisites

• Node.js 18+, pnpm 10+ (corepack enable)

• A Bitbucket Server Personal Access Token — profile → Manage Account → HTTP Access Tokens, with repository read + pull request write

• Windows, macOS and Linux. Only Linux needs a package for bb login (OS keyring): sudo apt install -y libsecret-1-0 gnome-keyring. Every command also works from BITBUCKET_TOKEN.

Install

pnpm install
pnpm build        # core first, then mcp and cli

Entry points: packages/mcp/dist/index.js, packages/cli/dist/index.js.

Quick start

MCP server

claude mcp add mcp-bitbucket \
  -e BITBUCKET_URL=https://bitbucket.example.com \
  -e BITBUCKET_TOKEN=your-personal-access-token \
  -- node /absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js

Or in .mcp.json (${VAR} is expanded by Claude Code, so no secret is committed):

{
  "mcpServers": {
    "mcp-bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "${BITBUCKET_URL}",
        "BITBUCKET_TOKEN": "${BITBUCKET_TOKEN}"
      }
    }
  }
}

HTTP transport instead of stdio: node packages/mcp/dist/index.js --http (port 3000) or MCP_HTTP_PORT=8080 node …. Routes: POST /mcp, GET /mcp (SSE), DELETE /mcp.

bb CLI

pnpm --filter @cuonghuunguyen/cli link --global
bb login          # or export BITBUCKET_URL / BITBUCKET_TOKEN
bb whoami         # proves authentication — `bb ping` only proves reachability
bb pr get 42      # repository comes from the git origin remote

Command surface: packages/cli/README.md or bb --help.

Claude Code skill

npx skills add . -a claude-code -g   # global: ~/.claude/skills
npx skills add . -a claude-code      # project scope: ./.claude/skills

Run from packages/skill. skills works on Windows, macOS and Linux, and installs into any of its 75+ supported agents.

Needs bb on PATH and a resolvable credential.

Configuration

Environment variables. A .env in the working directory is loaded automatically (cp .env.example .env) — an MCP server launched with a different cwd will not see it, so prefer real environment variables there. The MCP server validates them at startup; the CLI also accepts --url / --token, which win over everything, and falls back to the OS keyring when neither the flags nor the variables are set.

Limits

The caps in packages/core/src/operations/caps.ts are env-overridable: BITBUCKET_DIFF_MAX_CHARS (60000), BITBUCKET_DIFF_HEAD_RATIO (0.6), BITBUCKET_DIFF_CONTEXT_LINES (3), BITBUCKET_DIFF_FETCH_MAX_CHARS (12000000), BITBUCKET_DIFF_CACHE_ENTRIES (4), BITBUCKET_CHANGED_FILES_MAX_ITEMS (1000), BITBUCKET_CHANGED_FILES_STATS_MAX_FILES (500), BITBUCKET_REQUEST_TIMEOUT_MS (30000). Two limits are fixed in code and not overridable: the 500 KB single-file ceiling (operations/repository.ts) and the code-search bounds (operations/search.ts). Truncation is never silent — the note names the parameter and the variable that lift the cap, and lists every elided hunk header.

Permissions

Two independent guards.

MCP_PERMISSION_MODE — MCP server only. Every tool is classified read, write or destructive in packages/mcp/src/permissions.ts; a forbidden tool is both hidden from ListTools and refused when called by name.

The CLI does not read it. A readonly deployment does not stop bb review merge.

Repository allowlist — both entry points. BITBUCKET_ALLOWED_PROJECTS / BITBUCKET_ALLOWED_REPOS take comma-, semicolon- or space-separated patterns: PROJ, PROJ/*, PROJ/repo-a. The check runs inside the shared client before any socket opens, so every tool and every bb command inherits it. Unset means every repository. Case-insensitive; personal repos are project ~username. A malformed pattern is dropped, never widened — a value made only of malformed patterns allows nothing.

Tools

29 MCP tools: 17 read, 9 write, 3 destructive. Full parameters in docs/tools.md.

Notable defaults

• Resolved discussion is hidden. get_pull_request_comments / bb comment ls need includeResolved (--include-resolved) to show resolved threads and tasks; the reply says how many it hid. An explicit state filter overrides the default.

• Reviews are drafted, not posted. add_pr_draft_comment / bb review draft store an invisible comment; submit_pr_review publishes every pending comment with a verdict as one notification. pending: false (--no-pending) posts immediately; discard_pr_draft_review throws the draft away.

• bb ping ≠ authentication. /application-properties answers 200 anonymously on many instances. bb whoami is the authentication check.

Development

pnpm build | typecheck | test | lint | format | clean
pnpm dev:mcp                 # MCP server from source (tsx)
pnpm cli pr ls               # bb from source
pnpm --filter @cuonghuunguyen/core test

The layering rule that keeps the adapters from drifting:

• core knows nothing about MCP or the CLI — no MCP SDK, no yargs, no stdout. Operations take a client plus params and return structured data or throw.

• Adapters own input validation and output shape — zod plus the MCP result shape in mcp, yargs plus text/--json in cli. Neither leaks into core.

• Error messages are written once, in core, with {projects} / {login} style placeholders each adapter renders in its own vocabulary — the same failure says "use list_projects" to a model and "use bb project ls" to you.

• A new capability is an operation plus a formatter in core, then a thin adapter in each of mcp and cli.

Docker

The image carries the MCP server only.

docker build -t mcp-bitbucket .
docker run -i --rm -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… mcp-bitbucket
docker run --rm -p 3000:3000 -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… -e MCP_HTTP_PORT=3000 mcp-bitbucket

Troubleshooting

docs/troubleshooting.md. The three most common: a tool missing from the client list means MCP_PERMISSION_MODE hid it (an unrecognised value hides all 29); Refused: … outside the configured repository allowlist means the allowlist does not cover that repo; fewer comments than the web UI means resolved threads are hidden.

Limitations

• Bitbucket Server only; no Bitbucket Cloud, no OAuth/SSO/app passwords.

• bb login stores credentials in the OS keyring only — no plaintext store, no --password.

• No webhooks or event-driven mode; the server answers tool calls.

• Diffs are server-rendered unified diff text; inline comments anchored into the diff are not exposed.

• search_code needs the instance code index: default branch, whole words, no regex.

• MCP_PERMISSION_MODE gates the MCP server only; the allowlist gates both.