适合谁
- 使用自托管 Bitbucket Server/Data Center 的团队，希望通过对话式界面管理 PR 工作流
- 需要在 CI/CD 或代理环境中以只读方式安全访问 Bitbucket 数据的场景
- 希望在零信任网络架构下通过自定义请求头访问 Bitbucket 的组织
B
56FMRS · C
该服务器围绕 Bitbucket Server 拉取请求全流程提供了较为完整的工具集，涵盖项目/仓库发现、PR 创建到合并、评论与批量审阅、代码搜索与文件浏览，并支持只读模式和自定义请求头以适配企业网络环境；使用前需妥善保护认证凭据，并留意非只读模式下写操作的不可逆性。
Bitbucket Server MCP 是一个基于 Node.js 的 MCP 服务器，通过 Bitbucket Server REST API 提供项目与仓库浏览、拉取请求全生命周期管理（创建、更新、审批、合并、拒绝）、代码搜索、文件读取、分支与提交历史查看、评论管理以及 CI/CD 代码洞察（如 SonarQube）等能力。支持通过环境变量配置默认项目、只读模式和自定义 HTTP 请求头（适用于零信任令牌或代理场景）。
工具能力
list_projects
列出所有可访问的 Bitbucket 项目及其详情，便于发现项目和获取正确的项目 key。
list_repositories
浏览指定项目或所有可访问项目下的仓库，返回克隆地址等元数据。
create_pull_request
创建新的拉取请求，支持指定源/目标分支、审阅者，并可用于跨仓库（fork）场景。
update_pull_request
以读取-修改-写入的方式安全更新拉取请求的标题、描述或审阅者，未修改字段保持不变。
get_pull_request
获取拉取请求的详细信息，包括状态、审阅者、提交等元数据。
merge_pull_request
合并已批准的拉取请求，支持合并提交、压缩合并或快进合并策略。
decline_pull_request
拒绝不应合并的拉取请求，并可附带说明原因。
add_comment
在拉取请求中添加评论，支持 Markdown 和多级回复，可发布为公开或待发布草稿。
add_comment_inline
在拉取请求的代码差异中添加行内评论。
get_diff
获取拉取请求的代码差异，支持设置上下文行数及单文件最大显示行数以处理大文件。
get_reviews
获取拉取请求的审阅历史、批准状态及审阅者反馈。
get_activities
获取拉取请求的完整活动时间线，包括评论、审阅、提交等事件。
get_comments
从拉取请求活动中筛选出评论内容，便于专注于讨论内容。
search
跨仓库搜索代码和文件内容，支持按项目/仓库过滤，仅在仓库默认分支上生效。
get_file_content
读取仓库中指定文件的内容，支持分页处理大文件。
browse_repository
浏览仓库的目录结构，探索项目组织方式。
list_pull_requests
按状态、作者或方向筛选并列出仓库中的拉取请求。
list_branches
列出仓库分支，识别默认分支并显示各分支最新提交信息。
list_commits
列出仓库提交历史，支持按分支和作者过滤。
delete_branch
删除仓库中的分支，内置防止删除默认分支的安全检查。
approve_pull_request
以当前认证用户身份批准拉取请求。
unapprove_pull_request
撤销对拉取请求的批准。
edit_comment
编辑拉取请求中已有评论的文本内容，需提供评论版本号以进行乐观锁校验。
delete_comment
删除拉取请求中的评论，需提供评论版本号以进行乐观锁校验。
publish_review
一次性发布所有待发布的草稿评论，并可设置审阅状态（批准/需要修改）及总体评论。
get_code_insights
获取拉取请求的 Code Insights 报告（如 SonarQube、安全扫描等）及其注释。
get_dashboard_pull_requests
跨所有仓库列出当前认证用户相关的拉取请求，如待审阅、本人发起或参与的 PR。
安装接入
- 确保已安装 Node.js >= 16。
- 可选：通过 Smithery 一键安装（
npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude），或手动安装：npm install后执行npm run build。 - 在 MCP 客户端配置文件中添加服务器条目，设置
command为node，args指向构建产物build/index.js。 - 配置环境变量：
BITBUCKET_URL（必填），以及BITBUCKET_TOKEN或BITBUCKET_USERNAME/BITBUCKET_PASSWORD二选一用于认证；可选设置BITBUCKET_DEFAULT_PROJECT、BITBUCKET_READ_ONLY、BITBUCKET_CUSTOM_HEADERS、BITBUCKET_LOG_PATH、BITBUCKET_DIFF_MAX_LINES_PER_FILE。 - 重启客户端使配置生效。
claude_desktop_config.json
{"mcpServers":{"bitbucket":{"command":"node","args":["/path/to/bitbucket-server/build/index.js"],"env":{"BITBUCKET_URL":"https://your-bitbucket-server.com","BITBUCKET_TOKEN":"your-access-token","BITBUCKET_DEFAULT_PROJECT":"your-default-project"}}}}
选型与风险
不适合谁
- 使用 Bitbucket Cloud（bitbucket.org）而非 Bitbucket Server/Data Center 的用户，该服务器面向 Server API
- 不希望以 Node.js 进程方式在本地运行 MCP 服务器的用户
所需权限
- 需要 Bitbucket Server 的个人访问令牌，或用户名/密码基本认证凭据
- 凭据权限决定可执行的操作范围，写操作（创建/合并/评论/删除分支等）需要相应的仓库写权限
- 可选的自定义 HTTP 请求头会随所有请求发送，需妥善管理其中可能包含的令牌
风险与副作用
- 认证令牌或密码以环境变量明文形式配置，需注意存储和传输安全
- 非只读模式下模型可直接执行合并、拒绝、删除分支、删除评论等不可逆或影响协作的操作，存在误操作风险
- 日志文件默认写入本地磁盘（`~/.bitbucket-server-mcp/bitbucket.log`），可能包含敏感操作记录
常见排障
- 确认 `BITBUCKET_URL` 及认证信息（Token 或用户名/密码）配置正确且账号有相应仓库权限
- 若写操作被拒绝，检查是否误设置了 `BITBUCKET_READ_ONLY=true`
- 若某些操作提示项目未指定，检查是否需要设置 `BITBUCKET_DEFAULT_PROJECT` 或在调用时显式传入 `project` 参数
- 查看日志文件（默认 `~/.bitbucket-server-mcp/bitbucket.log`，或 `BITBUCKET_LOG_PATH` 指定路径）定位具体错误
- 确认已执行 `npm install` 与 `npm run build`，且客户端配置中的路径指向正确的 `build/index.js`
使用场景
在 AI 助手中直接创建、审阅、批准和合并 Bitbucket Server 拉取请求
跨项目搜索代码、浏览仓库结构并读取文件内容
查看拉取请求的差异、评论、审阅状态与 CI/CD 代码洞察结果
管理分支（列出、过滤、删除已合并分支）和查看提交历史
支持客户端
Claude Desktop完整支持
VS Code完整支持