bitbucket-mcp

面向 Bitbucket Cloud 的 MCP 服务器。 拉取请求、代码审查、分支、源代码、流水线、Webhook 和变量，以受控的工具面而非原始 REST 调用的形式暴露。

为什么有这个项目

官方的 Atlassian MCP 只覆盖 Jira 和 Confluence。Bitbucket 被排除在外，因此每个仓库操作都退化为手写的 REST 调用：冗长的载荷、没有护栏，以及一个可以触及作用域允许的任何内容的令牌。

这个服务器从三个方面弥合了这一缺口：

• 精简的载荷。 响应被归一化到您实际使用的字段，因此一次 PR 审查所消耗的上下文只是原始 REST 响应的一小部分。

• 护栏在服务器端，而不是在提示词中。 受保护分支、破坏性操作上的 confirm 以及只读模式都在 HTTP 调用发出之前强制执行。

• 每个意图一个工具。 55 个工具覆盖审查、分支、流水线和 Webhook 工作流，而不是一个通用的 HTTP 逃生舱。

flowchart LR
  A["MCP client<br/>(Claude Code, Inspector)"] -->|stdio| B["bitbucket-mcp"]
  B --> C{"Guards"}
  C -->|"read only, confirm,<br/>protected branch,<br/>workspace lock"| D["Bitbucket Cloud<br/>REST API"]
  C -.->|refused before<br/>the HTTP call| A
  B --> E["git over SSH<br/>or HTTPS"]
  E --> F["Repository"]
  D -->|normalized,<br/>trimmed response| A

Related MCP server: Bitbucket MCP

安装

该包以 @marcusyoda/bitbucket-mcp 的形式发布在 npm 上。

要求

• Node >= 20

• 一个带作用域的 Atlassian API 令牌（参见 认证）

• 在 Bitbucket 上注册的 SSH 密钥，用于通过 SSH 使用 git_* 工具。如果改用 HTTPS 变体，则为可选项。

选项 1：npx，无需安装

最快的路径。将您的 MCP 客户端指向该包，让 npx 解析它：

npx -y @marcusyoda/bitbucket-mcp

选项 2：全局安装

npm install -g @marcusyoda/bitbucket-mcp
# or: pnpm add -g @marcusyoda/bitbucket-mcp
bitbucket-mcp

选项 3：从源码安装

git clone https://github.com/marcusyoda/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install
pnpm build          # dist/index.js

在您的 MCP 客户端中注册

Claude Code，通过 CLI

claude mcp add bitbucket \
  --env BITBUCKET_EMAIL=you@example.com \
  --env BITBUCKET_API_TOKEN=your-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- npx -y @marcusyoda/bitbucket-mcp

任何客户端，通过 .mcp.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@marcusyoda/bitbucket-mcp"],
      "env": {
        "BITBUCKET_EMAIL": "you@example.com",
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_DEFAULT_REPO": "your-repo-optional"
      }
    }
  }
}

改为从源码运行？将命令换成构建后的入口点：

{ "command": "node", "args": ["/abs/path/to/bitbucket-mcp/dist/index.js"] }

通过调用 get_current_user 验证连接：它会往返校验令牌并返回您的 Bitbucket 身份。

认证

认证采用 HTTP Basic，使用 email:api_token。在 id.atlassian.com > 管理账户 > 安全 > API 令牌 创建一个带作用域的 API 令牌。

令牌作用域（精细选择器，只创建您用到的）：

变量工具（*_variable*、list_deployment_*）需要 admin:repository:bitbucket。跳过该作用域没有问题：这些工具会返回 403，其他一切照常工作。

理由和完整的权限决策记录见 PERMISSIONS.md。

环境变量

将 .env.example 复制为 .env 用于本地运行。切勿提交它。

包的 .env 仅当环境中缺少 BITBUCKET_API_TOKEN 时才会被加载。这样，注入每个项目凭据的启动器总是优先，而来自其他工作区的杂散 .env 永远无法覆盖注入的令牌。

安全模型

• BITBUCKET_READ_ONLY=true 会在任何写入和破坏性工具触达 API 之前将其阻止。

• 破坏性工具（merge、decline、delete_*、stop_pipeline、git_commit、git_push、内联 PR 评论）需要 confirm: true。

• 创建 secured 变量也需要 confirm: true。

• 安全变量值在 API 中是只写的，永远不会被返回或记录。

• 受保护分支（BITBUCKET_PROTECTED_BRANCHES，默认为 main,dev）被硬性阻止直接变更：git_push、git_rebase（当检出时）、delete_branch 和 create_branch 拒绝以它们为目标，即使有 confirm 也不行。通过 PR 在那里落地变更：merge_pull_request 合并到受保护分支在 confirm: true 下是允许的。

• 工作区锁。 当 BITBUCKET_LOCK_WORKSPACE=true 时，任何指定其他工作区的调用都会被拒绝。专为从单个安装服务多个客户端的机器而构建。

工具

每个工具都接受可选的 workspace 和 repo 来覆盖环境默认值。

仓库和元信息： get_current_user、list_repositories、get_repository、create_repository

拉取请求： list_pull_requests、get_pull_request、get_pull_request_diff、get_pull_request_activity、create_pull_request、update_pull_request、approve_pull_request、unapprove_pull_request、request_changes_pull_request、decline_pull_request （需确认）、merge_pull_request （需确认）、list_pr_commits、get_diff

评论： list_pr_comments、add_pr_comment （内联需要确认）、reply_pr_comment、update_pr_comment、delete_pr_comment （需确认）、resolve_comment、react_pr_comment （实验性）

分支、源代码和 git： list_branches、get_branch、create_branch、delete_branch （需确认）、get_file_source、list_directory、clone_repo、clone_repo_https、git_commit （需确认）、git_rebase、git_push （需确认）、git_push_https （需确认）。所有推送和分支工具都拒绝受保护分支。

流水线： list_pipelines、get_pipeline、get_pipeline_steps、get_pipeline_step_log、trigger_pipeline、stop_pipeline （需确认）

变量： list_repo_pipeline_variables、upsert_repo_pipeline_variable、delete_repo_pipeline_variable （需确认）、list_workspace_variables、list_deployment_environments、list_deployment_variables、upsert_deployment_variable、delete_deployment_variable （需确认）

Webhooks： list_webhooks、get_webhook、create_webhook、update_webhook、delete_webhook （需确认）

git 使用 SSH 还是 HTTPS

clone_repo、git_commit、git_rebase 和 git_push 使用您的 SSH 密钥，而不是令牌。当 SSH 不可用时，clone_repo_https 和 git_push_https 使用 username:token 进行认证，并且需要 BITBUCKET_USERNAME。受保护分支防护对两种传输方式都适用。

已知限制

• react_pr_comment 是实验性的。 PR 评论上的表情符号反应是为 Bitbucket Data Center 而非 Cloud 记录的。该工具针对一个尽力而为的端点，如果您的 workspace 不支持它，可能会返回错误。

• resolve_comment 依赖于仓库是否支持评论线程解析。

• 没有端点可以列出自定义流水线期望哪些变量。该信息来自 bitbucket-pipelines.yml，使用 get_file_source 读取它。

• 存储的变量值需要管理员作用域才能读回。

开发

pnpm install
pnpm dev         # tsx watch
pnpm typecheck
pnpm build       # tsup, ESM
pnpm inspect     # build and open the MCP Inspector

项目规则和约定见 CLAUDE.md。贡献遵循 issue 优先的工作流：每个提交都在其标题中链接一个 issue，格式为 type(scope): subject [#N]。

使用它

MIT 许可，而且这是字面意思：在工作中使用它、商业使用、分叉它、将其嵌入您自己的工具中、重命名它。无需请求许可，除了保留许可声明外没有署名仪式。如果它为您节省了一个下午手写 REST 调用的时间，那它已经值回票价了。

缺少某个工具，或者遇到了此项目未覆盖的 Bitbucket 端点？ 打开一个 issue。欢迎提交拉取请求：唯一的内部规则是每个提交都在其标题中链接一个 issue，格式为 type(scope): subject [#N]。

参见 LICENSE。