mcp-bitbucket

面向 AI 代理及其旁边人类的 Bitbucket Server。无需克隆即可读取拉取请求及其差异，起草审查并附带结论发布，发布阻塞任务，浏览代码和提交，打开、合并或拒绝拉取请求——从 MCP 客户端、从 shell，或从你自己的 TypeScript 中完成。

仅支持 Bitbucket Server / Data Center。不支持 Bitbucket Cloud。

包

Claude Code / Claude Desktop 工具使用 → mcp。终端、脚本、CI、运行命令的代理 → cli。构建其他东西 → core。它们读取相同的凭据，并可并排安装。

Related MCP server: Atlassian Bitbucket MCP Server

先决条件

• Node.js 18+，pnpm 10+（corepack enable）

• Bitbucket Server 个人访问令牌——个人资料 → 管理账户 → HTTP 访问令牌，具有仓库读取 + 拉取请求写入权限

• 仅用于 bb login（操作系统密钥环）：sudo apt install -y libsecret-1-0 gnome-keyring。每个命令也可以从 BITBUCKET_TOKEN 工作。

安装

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

入口点：packages/mcp/dist/index.js、packages/cli/dist/index.js。

快速开始

MCP 服务器

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

或者在 .mcp.json 中（${VAR} 由 Claude Code 展开，因此不会提交秘密）：

{
  "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 传输而不是 stdio：node packages/mcp/dist/index.js --http（端口 3000）或 MCP_HTTP_PORT=8080 node …。路由：POST /mcp、GET /mcp（SSE）、DELETE /mcp。

bb CLI

pnpm --filter @mcp-bitbucket/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

命令面：packages/cli/README.md 或 bb --help。

Claude Code 技能

bash packages/skill/scripts/install.sh            # ~/.claude/skills/bitbucket-review
bash packages/skill/scripts/install.sh ./.claude  # project scope

需要 bb 在 PATH 上，并且凭据可解析。

配置

环境变量，仓库根目录的 .env 会自动加载（cp .env.example .env）。MCP 服务器在启动时验证它们；CLI 也接受 --url / --token，它们优先于一切。

限制

每个数字上限都位于 packages/core/src/operations/caps.ts 中，并且可以通过环境变量覆盖：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）。截断永远不会静默——注释会指出提升上限的参数和变量，并列出每个被省略的 hunk 头。

权限

两个独立的守卫。

MCP_PERMISSION_MODE — 仅 MCP 服务器。 每个工具在 packages/mcp/src/permissions.ts 中被分类为 read、write 或 destructive；被禁止的工具既从 ListTools 中隐藏，也会在按名称调用时被拒绝。

CLI 不读取它。readonly 部署不会阻止 bb review merge。

仓库允许列表 — 两个入口点。 BITBUCKET_ALLOWED_PROJECTS / BITBUCKET_ALLOWED_REPOS 接受逗号、分号或空格分隔的模式：PROJ、PROJ/*、PROJ/repo-a。检查在共享客户端内、任何套接字打开之前运行，因此每个工具和每个 bb 命令都继承它。未设置意味着每个仓库。不区分大小写；个人仓库是项目 ~username。格式错误的模式会被丢弃，绝不会扩大——仅由格式错误模式组成的值不允许任何内容。

工具

29 个 MCP 工具：17 个读取，9 个写入，3 个破坏性。完整参数在 docs/tools.md 中。

值得注意的默认值

• 已解决的讨论被隐藏。 get_pull_request_comments / bb comment ls 需要 includeResolved（--include-resolved）来显示已解决的线程和任务；回复会说明隐藏了多少。显式的 state 过滤器会覆盖默认值。

• 审查是草稿，而不是发布。 add_pr_draft_comment / bb review draft 存储一个不可见的评论；submit_pr_review 将所有待处理的评论连同结论作为一条通知发布。pending: false（--no-pending）立即发布；discard_pr_draft_review 丢弃草稿。

• bb ping ≠ 身份验证。 /application-properties 在许多实例上匿名返回 200。bb whoami 是身份验证检查。

开发

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

保持适配器不漂移的分层规则：

• core 对 MCP 或 CLI 一无所知 — 没有 MCP SDK，没有 yargs，没有 stdout。操作接受客户端和参数，返回结构化数据或抛出异常。

• 适配器拥有输入验证和输出形状 — mcp 中的 zod 加上 MCP 结果形状，cli 中的 yargs 加上文本/--json。两者都不会泄漏到 core 中。

• 错误消息在 core 中只写一次，使用 {projects} / {login} 风格的占位符，每个适配器用自己的词汇渲染——同一个失败对模型说“使用 list_projects”，对你说“使用 bb project ls”。

• 新能力 是 core 中的一个操作和一个格式化器，然后是 mcp 和 cli 中各自的薄适配器。

Docker

镜像仅携带 MCP 服务器。

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

故障排除

docs/troubleshooting.md。最常见的三种：客户端列表中缺少工具意味着 MCP_PERMISSION_MODE 隐藏了它（无法识别的值会隐藏全部 29 个）；Refused: … outside the configured repository allowlist 意味着允许列表未覆盖该仓库；评论少于 Web UI 意味着已解决的线程被隐藏。

限制

• 仅 Bitbucket Server；不支持 Bitbucket Cloud、OAuth/SSO/应用密码。

• bb login 仅将凭据存储在操作系统密钥环中——没有明文存储，没有 --password。

• 没有 Webhook 或事件驱动模式；服务器响应工具调用。

• 差异是服务器渲染的统一差异文本；锚定在差异中的内联评论不会暴露。

• search_code 需要实例代码索引：默认分支、整词、无正则表达式。

• MCP_PERMISSION_MODE 仅限制 MCP 服务器；允许列表限制两者。