Bitbucket Server MCP

Name: Bitbucket Server MCP
Author: garc33

本地服务

github.com/garc33版本控制695 天前更新

代码仓库

关于 Bitbucket Server MCP

Bitbucket Server MCP 是面向 Bitbucket Server 的拉取请求管理服务，供编码 Agent 和代码审查流程使用。它还提供仓库浏览、代码搜索、分支与提交记录等操作。

主要功能

01创建、更新和合并拉取请求
02查看审查、评论与差异
03按条件发现拉取请求
04浏览项目、仓库和分支
05搜索代码并读取文件
06查看提交构建状态

适用场景

01提交功能或修复供团队审查
02检查拉取请求的审查与构建进度
03查找项目中的仓库或代码
04清理已合并分支

MCP 相关

作为 MCP 服务，它向 MCP 客户端提供 Bitbucket Server API 工具，用于管理拉取请求、浏览仓库及搜索代码。

#bitbucket #mcp #pull-request-management

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "bitbucket-server": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli"
      ]
    }
  }
}

启动命令npx -y @smithery/cli

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@smithery/clistdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Bitbucket Server MCP

用于管理 Bitbucket Server Pull Request 的 MCP（模型上下文协议）服务。此服务提供工具和资源，可通过 MCP 协议与 Bitbucket Server API 交互。

✨ 新功能

🔧 自定义 HTTP 标头：通过 BITBUCKET_CUSTOM_HEADERS 环境变量为所有请求添加自定义标头（适用于 Zero Trust 令牌或代理）
📋 PR 发现：使用 list_pull_requests 按状态、作者或方向列出和筛选 Pull Request（修复 #14）
🌿 分支管理：使用 list_branches 列出分支并检测默认分支，使用 delete_branch 删除已合并的分支
📝 提交历史：使用 list_commits 按分支和作者筛选并浏览提交历史
✅ PR 审批：使用 approve_pull_request 和 unapprove_pull_request 批准或撤销对 Pull Request 的批准
🔍 高级搜索：使用 search 工具搜索多个仓库中的代码和文件，并按项目／仓库筛选
📄 文件操作：使用 get_file_content 读取文件内容，使用 browse_repository 浏览仓库目录
💬 评论管理：使用 get_comments 工具提取和筛选 PR 评论
🔍 项目发现：使用 list_projects 列出所有可访问的 Bitbucket 项目
📁 仓库浏览：使用 list_repositories 浏览多个项目中的仓库
🔧 灵活的项目支持：默认项目改为可选项——可针对每条命令指定项目，或使用 BITBUCKET_DEFAULT_PROJECT
📖 增强文档：改进 README，增加使用示例并提供更完善的配置指南

要求

Node.js >= 22

安装

通过 Smithery 安装

通过 Smithery 为 Claude Desktop 自动安装 Bitbucket Server：

npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude

通过 npm 安装

此服务已发布到 npm，包名为 @garc33/bitbucket-server-mcp-server。你可以使用 npx 直接运行：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@garc33/bitbucket-server-mcp-server"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_TOKEN": "your-access-token"
      }
    }
  }
}

也可以全局安装并使用 bitbucket-server-mcp 命令：

npm install -g @garc33/bitbucket-server-mcp-server

手动安装

npm install

构建

npm run build

功能

此服务提供以下工具，可全面集成 Bitbucket Server：

`list_projects`

发现和浏览 Bitbucket 项目：列出所有可访问项目及其详细信息。对于发现项目以及查找其他操作所需的正确项目键，此工具必不可少。

使用场景：

不知道确切的项目键时，查找可用项目
探索项目结构和权限
发现你有权访问的新项目

参数：

limit：返回的项目数量（默认值：25，最大值：1000）
start：分页起始索引（默认值：0）

`list_repositories`

浏览和发现仓库：浏览指定项目中的仓库，或浏览所有可访问项目中的仓库。返回全面的仓库信息，包括克隆 URL 和元数据。

使用场景：

查找其他操作所需的仓库标识
探索多个项目中的代码库结构
发现你有权访问的仓库
浏览指定项目中的仓库

参数：

project：Bitbucket 项目键（可选；未提供时使用 BITBUCKET_DEFAULT_PROJECT）
limit：返回的仓库数量（默认值：25，最大值：1000）
start：分页起始索引（默认值：0）

`create_pull_request`

提议代码更改以供审查：创建新的拉取请求，以提交代码更改、请求审查或合并功能分支。自动处理分支引用和审查者分配。

使用场景：

提交功能开发以供审查
提议修复错误
请求集成功能分支中的代码
协作进行代码更改

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必需）：仓库标识
title（必需）：清晰、明确的 PR 标题
description：详细描述及背景信息（支持 Markdown）
sourceBranch（必需）：包含更改的源分支
targetBranch（必需）：用于合并的目标分支
reviewers：审查者用户名数组
sourceProject：源仓库的项目键（用于来自派生仓库的跨仓库 PR）
sourceRepository：源仓库的标识（用于来自派生仓库的跨仓库 PR）
includeDefaultReviewers：自动获取并包含为目标分支配置的默认审查者（默认值：true）

`update_pull_request`

安全更新拉取请求：修改现有拉取请求的标题、描述或审查者，同时不丢失任何元数据。采用读取-修改-写入模式，以保留所有未明确更改的字段。

使用场景：

创建 PR 后修正标题或描述
添加或替换审查者，同时保留现有审查者
更新 PR 元数据而不影响审批状态

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必需）：仓库标识
prId（必需）：要更新的拉取请求 ID
title：新标题（若省略，则保留当前标题）
description：新描述（若省略，则保留当前描述）
reviewers：由用户名数组组成的新审查者列表（若省略，则保留当前审查者）

`get_pull_request`

全面的 PR 信息：获取详细的拉取请求信息，包括状态、审查者、提交和所有元数据。了解 PR 状态后再采取操作至关重要。

使用场景：

检查 PR 审批状态
查看 PR 详情和进度
在合并前了解更改内容
监控 PR 状态

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必需）：仓库标识
prId（必需）：拉取请求 ID

`get_build_status`

读取提交的构建状态和 CI 构建 URL，包括 Jenkins 链接。使用现有 Bitbucket 凭据，并支持只读模式。

参数：

commitHash（必需）：完整的 40 字符提交哈希；使用 PR 的 fromRef.latestCommit。
limit：每页状态数（默认值：25，最大值：100）。
start：页面偏移量（默认值：0）；使用 nextPageStart 获取下一页。

调用 GET /rest/build-status/1.0/commits/{commitHash} 并返回 Bitbucket 响应，其中包含每个构建的 state 和 url。空列表表示没有记录构建状态。API／身份验证失败会作为错误报告，而非空列表。

使用 npm run build 重新构建本地安装后，在客户端中重启其 MCP 连接，以发现新工具。无需更改凭据。

`merge_pull_request`

整合已批准的更改：将已批准的拉取请求合并到目标分支。支持根据工作流偏好选择不同的合并策略。

使用场景：

完成代码审查流程
整合已批准的功能
将错误修复应用到主分支
发布代码更改

参数：

project：Bitbucket 项目键（可选；如果未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：拉取请求 ID
message：自定义合并提交消息
strategy：合并策略：
- merge-commit（默认）：创建合并提交并保留历史记录
- squash：将所有提交合并为一个
- fast-forward：移动分支指针，不创建合并提交

`decline_pull_request`

拒绝不合适的更改：拒绝不应合并的拉取请求，并向作者提供反馈。

使用场景：

拒绝不符合标准的更改
关闭与项目方向冲突的 PR
要求进行重大返工
阻止不需要的代码整合

参数：

project：Bitbucket 项目键（可选；如果未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：拉取请求 ID
message：拒绝原因（便于向作者提供反馈）

`add_comment`

参与代码审查：在拉取请求中添加评论，用于提供审查反馈、讨论和协作。支持串接对话。

使用场景：

提供代码审查反馈
询问有关特定更改的问题
提出改进建议
参与技术讨论
记录审查决定

参数：

project：Bitbucket 项目键（可选；如果未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：拉取请求 ID
text（必填）：评论内容（支持 Markdown）
parentId：用于串接回复的父评论 ID
state：评论状态：OPEN（默认，立即发布）或 PENDING（草稿，在发布审查前仅你可见）

`get_diff`

分析代码更改：获取代码差异，准确显示拉取请求中新增、删除或修改的内容。支持按文件截断，便于有效处理大型差异。

使用场景：

审查特定代码更改
了解修改范围
在合并前分析影响
检查实现细节
评估代码质量
处理大型文件，避免输出过多内容

参数：

project：Bitbucket 项目键（可选；如果未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：拉取请求 ID
contextLines：更改周围的上下文行数（默认：10）
maxLinesPerFile：每个文件显示的最大行数（可选；如果未指定，则使用 maxLinesPerFile env var；设为 0 表示不限制）

大型文件处理： 当文件超过 maxLinesPerFile 限制时，显示内容包括：

文件头和元数据（始终保留）
从文件开头显示允许行数的前 60%
包含文件统计信息的截断提示
从文件末尾显示允许行数的后 40%
清楚说明如何查看完整差异

`get_reviews`

跟踪审查进度：获取审查历史记录、批准状态和审查者反馈，以了解审查状态。

使用场景：

检查 PR 是否已准备好合并
查看谁审查了这些更改
了解审查反馈
监控批准要求
跟踪审查进度

`get_activities`

检索拉取请求活动：获取拉取请求的完整活动时间线，包括评论、评审、提交和其他事件。

使用场景：

阅读评论讨论和反馈
查看完整的 PR 时间线
跟踪 PR 中添加或移除的提交
查看审批和评审历史
了解 PR 的完整生命周期

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：拉取请求 ID

`get_comments`

仅提取 PR 评论：筛选拉取请求活动，仅返回评论，便于专注查看讨论内容，而不受评审或其他活动干扰。

使用场景：

阅读 PR 讨论串
提取反馈和问题
专注查看评论内容，避免干扰
分析对话脉络

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：拉取请求 ID

`search`

高级代码和文件搜索：使用 Bitbucket 搜索 API 跨仓库搜索，支持按项目或仓库筛选，并优化查询。搜索范围包括文件内容和文件名。注意：搜索仅适用于仓库的默认分支。

使用场景：

在多个项目中查找特定代码模式
按名称或内容定位文件
在特定项目或仓库中搜索
按文件扩展名筛选

参数：

query（必填）：搜索查询字符串
project：用于限定搜索范围的 Bitbucket 项目键
repository：用于指定仓库搜索范围的仓库 slug
type：查询优化方式——"file"（为查询加上引号，以精确匹配文件名）或 "code"（默认搜索行为）
limit：返回结果数（默认值：25，最大值：100）
start：分页起始索引（默认值：0）

查询语法示例：

"README.md" - 查找完全匹配的文件名
config ext:yml - 在 YAML 文件中查找 config
function project:MYPROJECT - 在指定项目中搜索 "function"
bug fix repo:PROJ/my-repo - 在指定仓库中搜索

`get_file_content`

分页读取文件内容：从仓库中检索特定文件的内容，并支持对大型文件进行分页读取。

使用场景：

阅读源代码文件
查看配置文件
提取文档内容
检查特定版本的文件

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
filePath（必填）：仓库中的文件路径
branch：分支或提交哈希（可选；默认为 main/master）
limit：每次请求的最大行数（默认值：100，最大值：1000）
start：分页起始行号（默认值：0）

`browse_repository`

浏览仓库结构：浏览仓库中的文件和目录，以了解项目组织方式并定位特定文件。

使用场景：

探索仓库结构
浏览目录树
查找文件和文件夹
了解项目组织方式

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
path：要浏览的目录路径（可选；默认为根目录）
branch：分支或提交哈希（可选；默认为 main/master）
limit：返回项目的最大数量（默认值：50）

`list_pull_requests`

发现并筛选拉取请求：列出仓库中的拉取请求，并可按状态、作者和方向筛选。返回 PR 元数据，包括标题、作者、分支、审阅者和状态。

使用场景：

查找仓库中未关闭的 PR
列出自己的拉取请求
查看等待审阅的 PR
概览已合并或已拒绝的 PR
监控项目中的 PR 活动

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
state：按 PR 状态筛选——OPEN（默认）、MERGED、DECLINED 或 ALL
author：按作者用户名筛选（精确匹配）
direction：INCOMING（目标为此仓库的 PR，默认）或 OUTGOING（来自此仓库的 PR）
limit：返回的 PR 数量（默认值：25，最大值：1000）
start：分页起始索引（默认值：0）

`list_branches`

浏览仓库分支：列出仓库中的分支，并可选择筛选条件。识别默认分支，并显示每个分支的最新提交信息。

使用场景：

查找用于创建 PR 或检出的分支名称
在执行操作前确认分支是否存在
识别默认分支
按名称搜索分支

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
filterText：按分支名称筛选（不区分大小写的部分匹配）
limit：返回的分支数量（默认值：25，最大值：1000）
start：分页起始索引（默认值：0）

`list_commits`

浏览提交历史：列出仓库中的提交，并可按分支和作者筛选。可用于审阅变更、追踪贡献，或了解分支的演进过程。

使用场景：

审阅分支上的近期变更
查找特定作者的提交
在合并前追踪提交历史
了解分支的演进过程

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
branch：要列出提交的分支名称（默认为仓库的默认分支）
author：按作者姓名或邮箱筛选（不区分大小写的部分匹配，在客户端进行）
limit：返回的提交数量（默认值：25，最大值：1000）
start：分页起始索引（默认值：0）

`delete_branch`

清理已合并的分支：删除仓库中的分支。此操作包含安全检查，可防止删除默认分支。

使用场景：

PR 合并后清理功能分支
删除过时或已弃用的分支
维护和整理仓库

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
branch（必填）：要删除的分支名称

`approve_pull_request`

批准代码变更：以当前已通过身份验证的用户身份批准拉取请求。记录你对 PR 的批准，表示这些变更已准备好合并。

使用场景：

批准已审阅的拉取请求
表示已准备好合并
完成代码审查工作流

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：要批准的拉取请求 ID

`unapprove_pull_request`

撤回批准：移除你对拉取请求的批准。如果发现问题，或 PR 已发生变更，可使用此操作撤回先前的批准。

使用场景：

发现问题后撤回批准
PR 范围发生变化时移除批准
更正误操作导致的批准

参数：

project：Bitbucket 项目键（可选；若未提供，则使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：要撤回批准的拉取请求 ID

`edit_comment`

编辑现有评论：修改拉取请求中评论的文本。适用于已发布和待处理（草稿）评论。需要提供评论版本以进行乐观锁定。

使用场景：

修正审查评论中的拼写错误或格式问题
更新现有评论中的信息
重新格式化评论（例如，采用 Conventional Comments 风格）

参数：

project：Bitbucket 项目键（可选；未提供时使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：评论所属的拉取请求 ID
commentId（必填）：要编辑的评论 ID
text（必填）：新的文本内容（支持 Markdown）
version（必填）：用于乐观锁定的评论当前版本（来自 get_comments 或 add_comment 的响应）

`delete_comment`

删除评论：从拉取请求中移除评论。需要提供评论版本以进行乐观锁定。

使用场景：

移除错误发布的评论
清理不再需要的草稿评论

参数：

project：Bitbucket 项目键（可选；未提供时使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：评论所属的拉取请求 ID
commentId（必填）：要删除的评论 ID
version（必填）：用于乐观锁定的评论当前版本

`publish_review`

发布批量审查：一次性发布所有待处理（草稿）评论，还可选择设置审查状态并添加概述评论。这相当于在 Bitbucket UI 中点击“Finish review”。

使用场景：

一次性发布所有草稿审查评论
在发布审查评论的同时批准 PR
提出修改要求，并附上“需要修改”状态和反馈

参数：

project：Bitbucket 项目键（可选；未提供时使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：拉取请求 ID
commentText：审查的可选概述评论
participantStatus：可选的审查状态：APPROVED（可合并）或 NEEDS_WORK（需要修改）。一般反馈时省略。

`get_code_insights`

获取 CI/CD 分析结果：获取拉取请求的 Code Insights 报告（SonarQube、安全扫描等）及其注释。

使用场景：

检查 SonarQube 质量门状态
查看安全扫描结果
检查代码覆盖率指标
查看每个文件的 CI/CD 分析注释

参数：

project：Bitbucket 项目键（可选；未提供时使用 BITBUCKET_DEFAULT_PROJECT）
repository（必填）：仓库 slug
prId（必填）：拉取请求 ID

`get_dashboard_pull_requests`

跨仓库 PR 仪表板：列出已认证用户在所有仓库中的拉取请求。无需指定各个项目和仓库，即可查看需要审查的 PR、自己创建的 PR，或参与的 PR。

使用场景：

查看所有等待自己审查的 PR
列出自己在所有项目中未关闭的 PR
查找自己参与且最近已合并的 PR
概览自己的 PR 工作量

参数：

state：按 PR 状态筛选：OPEN（默认）、MERGED、DECLINED 或 ALL
role：按自己的角色筛选：AUTHOR、REVIEWER 或 PARTICIPANT
participantStatus：按自己的审查状态筛选：APPROVED、UNAPPROVED 或 NEEDS_WORK
order：排序顺序：OLDEST 或 NEWEST（默认）
closedSince：仅包含此时间戳（epoch ms）之后更新的已关闭 PR
limit：返回的 PR 数量（默认：25）
start：分页起始索引（默认：0）

使用示例

列出项目和仓库

# List all accessible projects
list_projects

# List repositories in the default project (if BITBUCKET_DEFAULT_PROJECT is set)
list_repositories

# List repositories in a specific project
list_repositories --project "MYPROJECT"

# List projects with pagination
list_projects --limit 10 --start 0

搜索和文件操作

# Search for README files across all projects
search --query "README" --type "file" --limit 10

# Search for specific code patterns in a project
search --query "function getUserData" --type "code" --project "MYPROJECT"

# Search with file extension filter
search --query "config ext:yml" --project "MYPROJECT"

# Browse repository structure
browse_repository --project "MYPROJECT" --repository "my-repo"

# Browse specific directory
browse_repository --project "MYPROJECT" --repository "my-repo" --path "src/components"

# Read file contents
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "package.json" --limit 20

# Read specific lines from a large file
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "docs/CHANGELOG.md" --start 100 --limit 50

使用拉取请求

# Create a pull request (using default project)
create_pull_request --repository "my-repo" --title "Feature: New functionality" --sourceBranch "feature/new-feature" --targetBranch "main"

# Create a pull request with specific project
create_pull_request --project "MYPROJECT" --repository "my-repo" --title "Bugfix: Critical issue" --sourceBranch "bugfix/critical" --targetBranch "develop" --description "Fixes critical issue #123"

# Get pull request details
get_pull_request --repository "my-repo" --prId 123

# Get only comments from a PR (no reviews/commits)
get_comments --project "MYPROJECT" --repository "my-repo" --prId 123

# Get full PR activity timeline
get_activities --repository "my-repo" --prId 123

# Merge a pull request with squash strategy
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash" --message "Feature: New functionality (#123)"

查找拉取请求

# List open PRs in a repository (default state: OPEN)
list_pull_requests --repository "my-repo"

# List all PRs regardless of state
list_pull_requests --repository "my-repo" --state "ALL"

# Find PRs by a specific author
list_pull_requests --repository "my-repo" --author "john.doe"

# List merged PRs with pagination
list_pull_requests --repository "my-repo" --state "MERGED" --limit 10 --start 0

分支管理

# List all branches in a repository
list_branches --repository "my-repo"

# Filter branches by name
list_branches --project "MYPROJECT" --repository "my-repo" --filterText "feature"

# Delete a merged branch
delete_branch --repository "my-repo" --branch "feature/completed-work"

提交历史

# List recent commits on the default branch
list_commits --repository "my-repo"

# List commits on a specific branch
list_commits --repository "my-repo" --branch "develop" --limit 10

# Filter commits by author
list_commits --repository "my-repo" --author "john.doe"

# Combine branch and author filters
list_commits --project "MYPROJECT" --repository "my-repo" --branch "main" --author "jane"

PR 批准工作流

# Approve a pull request
approve_pull_request --repository "my-repo" --prId 123

# Remove your approval
unapprove_pull_request --repository "my-repo" --prId 123

# Full workflow: review diff, approve, merge
get_diff --repository "my-repo" --prId 123
approve_pull_request --repository "my-repo" --prId 123
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash"

依赖项

@modelcontextprotocol/sdk - MCP 协议实现的 SDK
axios - 用于 API 请求的 HTTP 客户端
winston - 日志框架

配置

服务器需要在 VSCode MCP 设置文件中进行配置。以下是示例配置：

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-server/build/index.js"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        // Authentication (choose one):
        // Option 1: Personal Access Token
        "BITBUCKET_TOKEN": "your-access-token",
        // Option 2: Username/Password
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_PASSWORD": "your-password",
        // Optional: Default project
        "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
      }
    }
  }
}

环境变量

BITBUCKET_URL（必需）：Bitbucket Server 实例的基础 URL
身份验证（以下方式之一为必需）：
- BITBUCKET_TOKEN：个人访问令牌
- BITBUCKET_USERNAME 和 BITBUCKET_PASSWORD：基本身份验证凭据
BITBUCKET_DEFAULT_PROJECT（可选）：工具调用未指定项目时使用的默认项目键
BITBUCKET_DIFF_MAX_LINES_PER_FILE（可选）：差异中每个文件默认显示的最大行数。设置此项可防止大文件占据过多输出。可通过 get_diff 调用中的 maxLinesPerFile 参数覆盖。
BITBUCKET_LOG_PATH（可选）：日志文件的自定义路径（默认值：~/.bitbucket-server-mcp/bitbucket.log）
BITBUCKET_READ_ONLY（可选）：设为 true 以启用只读模式
BITBUCKET_CUSTOM_HEADERS（可选）：要添加到所有请求中的自定义 HTTP 标头列表，以逗号分隔（格式：Header-Name=value,Another-Header=value2）。适用于 Zero Trust 令牌或代理标头

注意：借助新增的可选项目支持，您现在可以：

设置 BITBUCKET_DEFAULT_PROJECT，以默认操作特定项目
使用 list_projects 查找可用项目
使用 list_repositories 浏览各项目中的存储库
在任何工具调用中指定 project 参数，以覆盖默认项目

只读模式

服务器支持只读模式，适用于需要防止对 Bitbucket 存储库进行任何修改的部署。启用后，只能使用安全且不会修改数据的操作。

启用只读模式：将环境变量 BITBUCKET_READ_ONLY=true

只读模式下可用的工具：

list_projects - 浏览并列出项目
list_repositories - 浏览并列出存储库
get_pull_request - 查看拉取请求详情
list_pull_requests - 列出并筛选拉取请求
get_diff - 查看代码更改和差异
get_reviews - 查看评审历史和状态
get_activities - 查看拉取请求时间线
get_comments - 查看拉取请求评论
search - 跨存储库搜索代码和文件
get_file_content - 读取文件内容
browse_repository - 浏览存储库结构
list_branches - 列出存储库分支
list_commits - 浏览提交历史
get_code_insights - 获取 CI/CD 分析报告和注释
get_dashboard_pull_requests - 列出已认证用户在所有存储库中的 PR

只读模式下禁用的工具：

create_pull_request - 创建新的拉取请求
update_pull_request - 更新拉取请求标题、描述或评审者
merge_pull_request - 合并拉取请求
decline_pull_request - 拒绝拉取请求
add_comment - 在拉取请求中添加评论
add_comment_inline - 在拉取请求中添加行内评论
edit_comment - 编辑现有评论
delete_comment - 删除评论
publish_review - 发布批量评审
delete_branch - 删除分支
approve_pull_request - 批准拉取请求
unapprove_pull_request - 撤销对 PR 的批准

行为：

如果未设置 BITBUCKET_READ_ONLY，或将其设为 true 以外的任何值，所有工具都会正常运行（向后兼容）
当 BITBUCKET_READ_ONLY=true 时，写操作会被过滤掉；调用这些操作时会返回错误
此模式非常适合生产环境部署、CI/CD 集成，或任何需要安全只读访问 Bitbucket 的场景

日志记录

服务器使用 Winston 记录所有操作，以便进行调试和监控。

日志文件位置（按优先级排序）：

BITBUCKET_LOG_PATH 环境变量 — 自定义路径
~/.bitbucket-server-mcp/bitbucket.log — 默认位置

如果日志目录不存在，系统会自动创建。

示例：在 MCP 配置中设置自定义日志路径：

{
  "env": {
    "BITBUCKET_LOG_PATH": "/var/log/bitbucket-mcp/server.log"
  }
}

自定义 HTTP 标头

你可以使用 BITBUCKET_CUSTOM_HEADERS 环境变量，为所有 API 请求添加自定义 HTTP 标头。这适用于 Zero Trust 安全令牌、代理标头，或基础设施所需的任何其他标头。

格式：以逗号分隔的键值对，值中可以包含等号：

Header-Name=value,Another-Header=value2

单个标头示例：

{
  "env": {
    "BITBUCKET_CUSTOM_HEADERS": "X-Zero-Trust-Token=your-token-here"
  }
}

多个标头示例：

{
  "env": {
    "BITBUCKET_CUSTOM_HEADERS": "X-Custom-Header=value1,X-Proxy-Auth=token123"
  }
}

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Bitbucket Server MCP

关于 Bitbucket Server MCP

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Bitbucket Server MCP

✨ 新功能

要求

安装

通过 Smithery 安装

通过 npm 安装

手动安装

构建

功能

list_projects

list_repositories

create_pull_request

update_pull_request

get_pull_request

get_build_status

merge_pull_request

decline_pull_request

add_comment

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

get_dashboard_pull_requests

使用示例

列出项目和仓库

搜索和文件操作

使用拉取请求

查找拉取请求

分支管理

提交历史

PR 批准工作流

依赖项

配置

环境变量

只读模式

日志记录

自定义 HTTP 标头

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

`list_projects`

`list_repositories`

`create_pull_request`

`update_pull_request`

`get_pull_request`

`get_build_status`

`merge_pull_request`

`decline_pull_request`

`add_comment`

`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`

`get_dashboard_pull_requests`