Bitbucket MCP Server

一个面向生产的 Model Context Protocol 服务器，用于从 Bitbucket Cloud 和 Bitbucket Server/Data Center 检索拉取请求元数据和差异，并支持可选开启的拉取请求评论。

Features

• 支持 Bitbucket Cloud 和自托管的 Bitbucket Server/Data Center。

• 提供聚焦于拉取请求元数据、差异、评审讨论以及一般或行内评论的工具。

• 支持 bearer 令牌和基本认证。

• 在 Bitbucket 提供时返回原始差异以及结构化的变更文件数据。

• 通过可配置的 glob 模式排除生成的文件、文件夹或文件类型。

• 在不破坏 UTF-8 字符的前提下限制大型差异。

• 使用 stdio，且不会向 stdout 写入破坏协议的日志。

• 默认保持评论创建功能禁用，并且不会批准、合并或以其他方式修改拉取请求。

Related MCP server: Atlassian Bitbucket MCP Server

Quick start

需要受支持的 Node.js LTS 版本（Node.js 22 或更高版本）。

git clone https://github.com/inceon/bitbucket-mcp.git
cd bitbucket-mcp
npm install
npm run build
cp .env.example .env

在你的 MCP 客户端配置中设置 BITBUCKET_URL 和 BITBUCKET_TOKEN，然后使用 node dist/index.js 启动编译后的服务器。该服务器有意不自行加载 .env 文件；MCP 客户端应直接传递环境变量。

Authentication

Bearer 认证是默认方式，推荐用于 Bitbucket Server/Data Center 的个人访问令牌：

BITBUCKET_URL=https://bitbucket.example.com/bitbucket
BITBUCKET_TOKEN=your-personal-access-token
BITBUCKET_AUTH_TYPE=bearer

对于需要基本认证的 Bitbucket Cloud API 令牌或应用密码：

BITBUCKET_URL=https://api.bitbucket.org
BITBUCKET_TOKEN=your-api-token-or-app-password
BITBUCKET_AUTH_TYPE=basic
BITBUCKET_USERNAME=your-bitbucket-username

仅授予凭证与你所启用工具所需的权限。创建评论需要创建拉取请求评论的权限。切勿提交凭证，也不要在问题报告中放置真实令牌。

Environment variables

服务器仅将启动错误写入 stderr，并从 Bitbucket HTTP 错误片段中隐藏已配置的凭证。

MCP configuration

Claude Desktop 配置：

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org",
        "BITBUCKET_TOKEN": "your-token"
      }
    }
  }
}

Codex config.toml 配置：

[mcp_servers.bitbucket]
command = "node"
args = ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"]

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://api.bitbucket.org"
BITBUCKET_TOKEN = "your-token"

Available tools

get_pull_request

返回拉取请求元数据，包括其描述、状态、作者、审阅者、分支、时间戳和链接。

{
  "name": "get_pull_request",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123
  }
}

get_pull_request_comments

以提供方原生评论对象的形式返回现有的一般讨论和行内讨论。在发布评审发现之前使用它，以考虑已有的反馈。当达到配置的检索上限时，commentsStatus.complete 为 false，reason 为 max_comments 或 max_pages。

get_pull_request_commits

返回当前拉取请求中的提供方原生提交。使用它可将评审发现追溯到其来源提交，或验证后续工作是否解决了该问题。当达到配置的检索上限时，commitsStatus.complete 为 false，reason 为 max_commits 或 max_pages。

get_pull_request_diff

返回 git 风格的评审差异以及可用的结构化变更文件。

{
  "name": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJECT_KEY",
    "repository": "my-repository",
    "pull_request_id": 123,
    "ignore_patterns": ["dist/**", "**/*.generated.ts", "package-lock.json"],
    "path": "src/service.ts",
    "context": 5,
    "ignore_whitespace": true,
    "renames": true
  }
}

差异输出既可以作为向后兼容的 JSON 文本提供，也可以作为 MCP structuredContent 提供，并带有已公布的输出模式。它包括：

• provider、pull_request_id、rawDiff、rawDiffBytes 和 rawDiffSource。对于 Cloud，rawDiffSource 为 provider_raw；对于本地规范化的 Server/Data Center 响应，则为 server_structured。

• truncated 以及 truncationReason：当达到上游 Cloud 读取限制时为 input_limit，当过滤后的结果超过 BITBUCKET_MAX_DIFF_BYTES 时为 output_limit，当 Server/Data Center 将其结构化差异标记为已截断时为 provider_limit。

• 可选的精简 files 条目仅包含 path、规范化的 status，以及针对重命名或复制的 oldPath。必填的 filesStatus 报告完整性；complete 为 false，reason 为 max_files、max_pages 或 unsupported，returned 反映实际返回的过滤后条目。

• 当排除规则生效时，可选的 ignored 元数据。

完整结果：

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 128,
  "rawDiffSource": "provider_raw",
  "files": [],
  "filesStatus": { "available": true, "complete": true, "returned": 0 },
  "truncated": false
}

有界部分结果：

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 200000,
  "rawDiffSource": "provider_raw",
  "files": [{ "path": "src/service.ts", "status": "modified" }],
  "filesStatus": {
    "available": true,
    "complete": false,
    "returned": 1,
    "reason": "max_pages"
  },
  "truncated": true,
  "truncationReason": "output_limit"
}

被截断的 rawDiff 是 UTF-8 安全的评审前缀，不一定是完整的行、hunk 或可应用的补丁。

结构化文件页会一直跟踪，直到完成或达到配置的文件/页数上限，然后规范化为精简的评审元数据，而不是返回提供方的哈希、链接和重复的路径结构。只有 HTTP 404 之后才会报告不可用的 diffstat 或 changes 端点。授权、速率限制、服务器、响应格式错误、超时和传输故障会导致工具调用失败，而不会静默省略元数据。

Cloud 的 rawDiff 保留提供方的原始响应。Server/Data Center 使用结构化的 /diff 响应，并将其文件、hunk、段和行规范化为 git 风格的评审文本；这避免了单独的 .diff 导出路由带来的特定版本故障。rawDiffSource 明确了这一区别。

两个提供方都支持 path，它是逐文件评审大型拉取请求的首选方式；返回的 files 元数据范围限定在同一路径内。renames 仅适用于 Cloud。context 映射到 Cloud 的 context 以及 Server/Data Center 的 contextLines。ignore_whitespace 映射到 Cloud 的 ignore_whitespace 以及 Server/Data Center 的 whitespace=ignore-all。当这些参数不存在时，不会更改提供方的默认行为。

模式使用相对于仓库的路径，并支持 *、** 和 ?。不包含 / 的模式（如 package-lock.json 或 *.png）可在任意位置匹配该文件名。结尾的斜杠表示递归排除整个目录。当排除规则生效时，响应中包含 ignored.patterns、ignored.files 和 ignored.rawDiffFiltered。rawDiffFiltered 为 false 表示 Cloud 提供方返回了无法安全过滤的非 git 差异格式；此时保留响应内容，而不是静默丢弃。

add_pull_request_comment

在拉取请求上创建一般评论、文件级评论或行内行评论。此写操作仅在 MCP 服务器环境中设置了 BITBUCKET_ENABLE_WRITE_TOOLS=true 时可用。

一般评论：

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "The implementation looks good. Please add a regression test for the empty input case."
  }
}

对新增行的行内评论：

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "Please handle an empty value here.",
    "file_path": "src/service.ts",
    "line": 42,
    "line_type": "added"
  }
}

使用 line_type 值 added、removed 或 context。新增行默认位于 new 一侧，删除行默认位于 old 一侧，上下文行默认位于 new 一侧；显式设置 line_side 可将上下文评论放在 old 一侧。对于文件级评论，请提供 file_path 而不提供行字段。对于 Server/Data Center 上的重命名文件，source_file_path 可以标识先前的路径。

经过认证的 Bitbucket 用户将成为评论作者。在批准 MCP 客户端中的工具调用之前，请检查目标工作区、仓库、拉取请求 ID 和评论文本。

Provider behavior

URL 的主机名决定提供方。bitbucket.org 和 api.bitbucket.org 使用 Bitbucket Cloud；所有其他主机使用 Server/Data Center。

Cloud URL 规范化为一个 /2.0 API 前缀，并使用：

• /repositories/{workspace}/{repository}/pullrequests/{id}

• /repositories/{workspace}/{repository}/pullrequests/{id}/diff

• /repositories/{workspace}/{repository}/pullrequests/{id}/diffstat

• /repositories/{workspace}/{repository}/pullrequests/{id}/comments（GET；启用后 POST）

• /repositories/{workspace}/{repository}/pullrequests/{id}/commits（GET）

Server/Data Center URL 保留诸如 /bitbucket 之类的上下文路径，规范化为一个 /rest/api/1.0 前缀，并使用：

• /projects/{project}/repos/{repository}/pull-requests/{id}

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff（规范化为 git 风格评审文本的结构化差异）

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff/{path}（按路径限定的结构化差异）

• /projects/{project}/repos/{repository}/pull-requests/{id}/changes

• /projects/{project}/repos/{repository}/pull-requests/{id}/comments（GET；启用后 POST）

• /projects/{project}/repos/{repository}/pull-requests/{id}/commits（GET）

可选的 diffstat 或 changes 请求在 HTTP 404 后报告 filesStatus.reason: "unsupported"。其他 HTTP、超时、传输和解析失败会导致工具调用失败，这样不完整的元数据就不会被误认为是完整响应。

Atlassian Rovo MCP

Atlassian 在文档中记录了仅限 Cloud 的 bitbucketPullRequest.diff 操作，但未发布其参数模式、输出结构、分页、过滤或截断约定。因此，此服务器保持以直接调用 Bitbucket API 为权威来源。只有在验证了实时的 tools/list 模式和受控的 diff 响应之后，才应添加 Rovo 适配器；它必须保持显式配置，并且不能替代 Server/Data Center 支持。请参阅 Atlassian 的受支持工具页面。

路线图

未来版本计划涵盖以下领域：

• 添加重试处理并改进速率限制诊断信息。

• 提供规范化的拉取请求输出，同时保留对提供商特定字段的访问。

• 添加用于列出拉取请求和获取构建状态的只读工具。

• 提供可选的 Streamable HTTP 传输，同时保持 stdio 为默认方式。

• 发布带版本号的版本，提供更简单的安装和升级路径。

写入操作默认保持禁用。批准、合并以及其他高影响的 Bitbucket 操作不在计划之内。欢迎通过 GitHub issues 提交想法和实现建议。

开发

npm run dev        # Run directly from TypeScript
npm run build      # Compile to dist/
npm test           # Run the test suite once
npm run test:watch # Run tests in watch mode
npm run check      # Build and test, matching CI

命令注册表将每个 MCP 工具隔离在 src/tools 下。在提交拉取请求之前，请先阅读 CONTRIBUTING.md。

安全

此服务器在内存中处理凭据，并且仅将其发送到配置的 BITBUCKET_URL。在启动服务器之前，请仔细审查该 URL。启用写入工具后，连接的 MCP 客户端可以以已认证的 Bitbucket 用户身份发布 PR 评论。如需私下报告漏洞，请遵循 SECURITY.md。

许可证

根据 MIT License 发布。