Bitbucket MCP Server

Bitbucket MCP 服务

适用于 Bitbucket 的 MCP 服务——专为需要像操作本地克隆一样处理远程仓库的 AI 编码 Agent 打造：grep 级别的快速代码搜索、窗口式文件读取、紧凑且节省 token 的响应，以及不会触发 Bitbucket 速率限制的传输层。

支持 Bitbucket Server / Data Center（主要目标）和 Bitbucket Cloud。

为什么推出 v3

	v2	v3
在仓库中搜索内容	1 次列表调用 + 最多 3,000 次文件 GET 调用	冷启动 1 次归档调用，热启动 0–1 次调用
搜索完整性	受服务器限流影响时会静默返回部分结果	完整，并报告所有上限
PR 差异 token	逐行 JSON（体积约为 4 倍）	原始统一差异
读取 100 行的窗口	2 次调用，传输整个文件	1 次调用，仅传输窗口内容
对超大文件的某个窗口执行 blame	最多 100 次调用	1 次调用
速率限制安全性	无（突发请求 → 429/403）	客户端节流，按 DC 的限制器设定
工具	33	25（定义上下文减少约 30%）

在一个正在运行的 Data Center 实例上测得：重复内容搜索从 519 次 API 调用 / 约 7 秒（在突发限流下仅找到 8 个真实匹配项中的 1 个）变为找到全部 8 个，仅需 0 次 API 调用 / 24 毫秒。完整设计和已验证的 API 调研：REVAMP_PLAN.md。

工具（25 个）

搜索（search）——仅限 Server/DC

• grep — 在文件内容中搜索，支持完整正则表达式和任意分支，就像在本地克隆中使用 ripgrep 一样。每个仓库 + 提交只下载一次 archive，以恒定内存流式处理，在进程内缓存，并在每次调用时检查新鲜度（响应包含 as_of <commit>）。省略 query 可仅按文件名执行 glob 列表查询。模式：content、files、count；glob、path、context、case_insensitive、max_results。
• search_code — 基于索引，在整个项目中通过一次调用搜索精确词项（仅默认分支、不区分大小写、不支持正则、文件小于 512 KiB、结果窗口约 1,000 条）。最适合跨仓库标识符查询；其他情况请使用 grep。
• search_repositories — 按名称 / 描述查找仓库。

拉取请求（pr_core）

• get_pull_request — 一次调用获取元数据 + 审核者状态 + 合并信息；include_comments / include_file_changes（默认为 true）、include_tasks、comment_limit。返回 version，供后续修改操作使用。
• list_pull_requests — 按仓库查询；省略 repository（Server）即可一次调用获取你在所有仓库中的 PR（通过 role 筛选）。
• create_pull_request、update_pull_request、merge_pull_request、decline_pull_request — 所有修改操作均可使用先前读取时获得的 version（省去一次读取；遇到 409 冲突时自动重新读取并重试一次）。

评论和任务（pr_comments）

• add_comment — 普通评论、线程回复、行内评论（file_path + line_number，或通过 code_snippet 自动定位）、代码 suggestion，或任务（severity: "BLOCKER"，Server）。附件通过 attachments 参数上传（Server）。
• manage_comment — 对任意评论或任务执行 edit / delete / resolve / reopen / to_task / to_comment，一次调用并使用 version。

审核（pr_review）

• get_pull_request_diff — 原始统一差异文本；使用 file_path（服务器端）、include_patterns / exclude_patterns、context_lines、ignore_whitespace 指定范围。
• set_review_status — APPROVED / NEEDS_WORK / UNAPPROVED（互斥；一次调用）。

提交（commits）

• list_pr_commits、list_branch_commits（服务器端 since-rev / merges 筛选；客户端 author / until / search 筛选采用有界分页遍历）、get_commit_detail（统一差异，或使用 detail: "files" 获取不含正文的已更改文件列表）。

分支（branches）

• list_branches、get_branch（分支及其 PR）、delete_branch（expected_head 可跳过查询调用）。

文件（files）

• get_file_content — 服务端分窗读取：start_line/line_count 仅传输指定窗口（每次调用 ≤5000 行）。读取整个文件或文件尾部时使用 full_content / 负数 start_line。
• get_file_blame — 在 1 次调用中获取指定行窗口的提交区间 blame（Server）。
• list_directory_content — 分页返回，内容紧凑。

附件（attachments，Server）/ 发现（discovery）

• manage_attachments（download 有大小上限，delete）、list_projects、list_repositories。

输出约定

• 批量内容（差异、文件、grep 结果）为纯文本，而非经过 JSON 转义的字符串；列表使用紧凑 JSON，不进行美化排版。日期采用 ISO-8601 格式。
• 源自内容的响应会带有 as_of <commit>，让 Agent 准确知道它看到的是哪个状态。
• 截断绝不会悄无声息——每次达到上限都会明确警告并提供继续操作的指引（next_start、“缩小 glob 范围”等）。
• 可变实体包含 version，因此修改后无需重新读取。

安装

需要 Node.js 22 或更高版本（18 和 20 已停止维护，不再接收安全修复）。

使用 npx（推荐）

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@nexus2520/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_USERNAME": "your.username",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

使用 Bitbucket Cloud 时，请使用 BITBUCKET_APP_PASSWORD 代替 BITBUCKET_TOKEN（并省略 BITBUCKET_BASE_URL）。

凭据配置指南：Cloud 应用密码 · Server/DC HTTP 令牌。

从源代码安装

git clone https://github.com/pdogra1299/bitbucket-mcp-server.git
cd bitbucket-mcp-server
npm install && npm run build
# point your MCP config at: node <repo>/build/index.js

配置

所有数值策略均可通过环境变量调整，没有任何硬编码值。完整列表见 src/config/index.ts（CONFIG_REFERENCE）。最重要的配置项如下：

变量	默认值	用途
BITBUCKET_RATE_LIMIT_RPS	5	客户端持续请求速率（DC 的每用户补充速率为 5/s）。0 表示禁用速率控制；如果你的账户获得了管理员速率限制豁免，请设置此值
BITBUCKET_RATE_LIMIT_BURST	50	突发容量（DC 服务端令牌桶容量为 60）
BITBUCKET_GLOBAL_MAX_CONCURRENCY	8	所有工具的最大并发在途请求数
BITBUCKET_SNAPSHOT_MAX_MB	256	内存中 grep 缓存的容量上限。0 = 纯流式处理（不保留内容，每次搜索仍需 2 次调用）
BITBUCKET_SNAPSHOT_MAX_FILE_KB	2048	扫描大于此值的文件，但不缓存
BITBUCKET_REF_RESOLVE_TTL_MS	15000	分支→SHA 新鲜度缓存；0 = 每次调用都进行验证
BITBUCKET_STREAM_ABORT_MB	2048	提取的 MB 数超过此值时中止归档扫描（改为逐文件进行有界扫描）
BITBUCKET_HTTP_TIMEOUT_MS	30000	单次请求超时时间
BITBUCKET_TOOL_GROUPS	all	以逗号分隔的工具组列表（经过验证，在分发时强制执行，验证失败时默认拒绝）
BITBUCKET_READ_ONLY	false	隐藏并拒绝所有会更改状态的工具（创建/更新/合并/拒绝 PR、评论、审查状态、删除分支、删除附件）
BITBUCKET_DISABLED_TOOLS	—	以逗号分隔的工具名称列表；无论工具组如何，都会将这些工具隐藏并拒绝调用
BITBUCKET_PROTECTED_BRANCHES	—	delete_branch 和 merge_pull_request 不会操作的分支名称/glob（main,release/*；嵌套分支请使用 release/**）
BITBUCKET_ATTACHMENT_ROOT	未设置 = 禁用上传	附件上传唯一允许读取的目录（限制在真实路径内，且仅允许普通文件）
BITBUCKET_ATTACHMENT_MAX_UPLOAD_MB / _DOWNLOAD_MB	25	附件上传/下载的大小上限
BITBUCKET_GREP_TIMEOUT_MS	20000	每次内容扫描的墙钟时间预算；超时后返回带有 PARTIAL 标记的结果
BITBUCKET_GREP_MAX_SCAN_LINE_CHARS	16384	超过此长度的行只计数并报告，不进行正则扫描（限制压缩文件中每行的正则开销）

grep 引擎的保障

• 内存有界：归档内容以流的形式处理，不会完整缓存在内存中；缓存设有严格的字节数上限，并采用 LRU 淘汰机制，且会跨分支按内容哈希去重。最坏情况下，内存占用为上限加上几 MB 的临时开销。
• 结果新鲜：每次查询都会重新解析分支头；分支移动后绝不会返回过时结果。通过此服务执行的合并／删除操作会立即使缓存失效。
• 结果完整：缓存限制不会缩小扫描范围——仍会扫描超大文件；只跳过真正的二进制文件，并在输出中统计这些文件。

速率限制

所有请求都会经过一个令牌桶，其容量依据 Bitbucket DC 的每用户限流器设置，因此可以避免 429，而不必在收到 429 后重试。如果你的实例仍然严格限流，错误消息会明确说明该怎么做——持久的解决方案是请 Bitbucket 管理员为服务帐户设置速率限制豁免（Admin → Rate limiting → Exemptions），然后设置 BITBUCKET_RATE_LIMIT_RPS=0。

安全性

此服务会执行参数来自大模型的工具调用，且通常使用具备写入权限的令牌。内置了以下控制措施：

• 按配置遵循最小权限原则。 BITBUCKET_READ_ONLY=true 会从 tools/list 和分发逻辑中移除所有变更类工具——建议仅需读取 PR、差异和代码的自主 Agent 使用。BITBUCKET_DISABLED_TOOLS 可禁用单个工具；BITBUCKET_PROTECTED_BRANCHES 会阻止针对指定分支或 glob 模式执行 delete_branch／merge_pull_request。每个工具都带有 MCP readOnlyHint／destructiveHint 注解，方便客户端控制是否需要确认。
• 请求路由不可被操控。 workspace、repository、提交 ID、附件 ID 和文件路径都经过字符集验证，并按 URL 路径段进行百分号编码，因此 PROJ/../../admin 或 repo?limit=1000 这样的值绝不会改变固定动词工具所访问的 REST 路由。
• 附件上传需显式启用，并受沙箱限制。 未设置 BITBUCKET_ATTACHMENT_ROOT 时，会拒绝 attachments 参数。设置后，实际路径（解析符号链接后）必须位于根目录内、必须是常规文件，且大小不得超出上限；所有拒绝都会使用同一条通用消息，避免工具成为文件系统存在性预言机。下载也有大小上限。
• 正则表达式拒绝服务防护。 调用方的正则表达式（grep 的 query、search_code 的 regex_filter）设有长度上限；若检测到无界量词包裹了含有无分隔符可变宽度重复的分组（(a+)+、(\w+\s*)*），则会在静态检查阶段拒绝；还会在 vm 超时限制下使用对抗性输入进行探测，并为每次扫描设置墙钟时间期限（BITBUCKET_GREP_TIMEOUT_MS），超时会标记部分结果，绝不静默处理。超过 BITBUCKET_GREP_MAX_SCAN_LINE_CHARS 的行会被跳过并计数。启动时还会启用 V8 的线性时间正则表达式回退机制，作为额外防护。
• 凭据卫生。 传输错误会先规范化为状态码、消息和响应头，再传递给处理程序；不会完整记录错误对象，日志行也会对 Authorization 一类的值进行脱敏。Cloud 分页只会跟随配置的源站中的 next URL。
• 依赖要求。 Node ≥ 22；npm run audit:prod 必须报告已发布依赖树中不存在高危或严重安全公告（由 CI 强制执行）。

为自主 Agent 推荐的部署方式：

"env": {
  "BITBUCKET_READ_ONLY": "true",
  "BITBUCKET_PROTECTED_BRANCHES": "main,release/*"
}

写入操作（评论、批准、合并）应通过单独的、需要人工确认的服务实例，或托管应用自身的审批流程执行。

从 v2 迁移

已移除的工具及其 v3 对应项（能力相同，工具更少）：

v2	v3
find_in_files	带 query 的 grep
search_files	不带 query 的 grep（使用 glob）
list_pr_tasks	get_pull_request + include_tasks: true
create_pr_task	add_comment + severity: "BLOCKER"
update_pr_task	manage_comment action: "edit"
delete_pr_task, delete_comment	manage_comment action: "delete"
set_pr_task_status	manage_comment action: "resolve" / "reopen"
convert_pr_item	manage_comment action: "to_task" / "to_comment"
set_pr_approval	set_review_status status: "APPROVED" / "UNAPPROVED"

相应更新 Claude Code 权限允许列表（mcp__bitbucket__*）。Diff 工具现在返回统一 diff 文本，而不是逐行 JSON——行号来自 @@ 标头。详情请见 CHANGELOG.md。

开发

npm run build   # tsc → build/
npm test        # build + node --test (unit + snapshot-engine tests)

架构：src/config（所有策略）· src/core（传输、快照引擎、缓存）· src/handlers（工具逻辑）· src/tools（定义、守卫、注册表）· src/formatting（精简输出）· src/types（单一总入口）。

许可证

MIT