Bitbucket MCP 服务器

npm version License: MIT

一个 MCP (模型上下文协议) 服务器，提供与 Bitbucket API 交互的工具，同时支持 Bitbucket Cloud 和 Bitbucket Server。

功能特性

可用工具 (共 29 个)

PR 核心 (`pr_core`)

get_pull_request - 获取完整的 PR 详情，包括评论、文件变更和合并信息
list_pull_requests - 列出 PR，支持过滤（状态、作者、分页）
create_pull_request - 创建新的拉取请求
update_pull_request - 更新 PR 详情（标题、描述、审查者、目标分支）
merge_pull_request - 使用多种策略合并拉取请求
decline_pull_request - 拒绝/驳回拉取请求

PR 评论 (`pr_comments`)

add_comment - 向 PR 添加常规评论、行内评论、嵌套评论或建议
delete_comment - 从拉取请求中删除评论

代码审查 (`pr_review`)

get_pull_request_diff - 结构化的逐行差异对比，包含 ADDED/REMOVED/CONTEXT 类型
set_pr_approval - 批准 (approved: true) 或取消批准 (approved: false) PR
set_review_status - 请求变更 (request_changes: true) 或移除请求 (false)

PR 任务 — 仅限 Bitbucket Server (`pr_tasks`)

list_pr_tasks - 列出拉取请求上的所有任务
create_pr_task - 在拉取请求上创建新任务
update_pr_task - 更新现有任务的文本
set_pr_task_status - 标记任务为完成 (done: true) 或重新打开 (done: false)
delete_pr_task - 从拉取请求中删除任务
convert_pr_item - 将评论转换为任务 (direction: "to_task") 或反之 ("to_comment")

提交 (`commits`)

list_pr_commits - 列出拉取请求中的所有提交
list_branch_commits - 列出分支中的提交，支持日期/作者/消息过滤
get_commit_detail - 通过 SHA 获取特定提交的结构化差异

分支 (`branches`)

list_branches - 列出分支，支持过滤和分页
get_branch - 获取详细的分支信息，包括关联的 PR 和统计数据
delete_branch - 删除分支

文件 (`files`)

list_directory_content - 列出仓库路径下的文件和目录
get_file_content - 获取文件内容，支持对大文件进行智能截断
search_files - 通过 glob 模式搜索文件（不区分大小写，类似于 VS Code 的 Ctrl+P）

搜索 — 仅限 Bitbucket Server (`search`)

search_code - 在仓库中搜索代码
search_repositories - 通过名称或描述搜索仓库

发现 (`discovery`)

list_projects - 列出所有可访问的 Bitbucket 项目/工作区
list_repositories - 列出项目内或所有可访问项目中的仓库

Token 优化

v2.0.0 在每次 LLM 请求中显著节省了 Token：

配置	暴露的工具	预估 Token
Bitbucket Server (所有组)	29	~5,100
Bitbucket Cloud (自动过滤)	21	~3,900
自定义组预设 (例如 `pr_core,pr_review,files`)	12	~2,100

Bitbucket Cloud 会自动隐藏 10 个仅限 Server 的工具，无需任何配置。

BITBUCKET_TOOL_GROUPS 允许您仅暴露与工作流相关的组 — 请参阅下方的工具组过滤。

Related MCP server: MCP Server

安装

使用 npx (推荐)

使用此 MCP 服务器最简单的方法是直接通过 npx：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

对于 Bitbucket Server：

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

从源码安装

克隆或下载此仓库
安装依赖：
```
npm install
```
构建 TypeScript 代码：
```
npm run build
```

身份验证设置

此服务器使用 Bitbucket 应用密码进行身份验证。

创建应用密码

登录您的 Bitbucket 账户
导航至：https://bitbucket.org/account/settings/app-passwords/
点击 "Create app password"
给它一个描述性标签（例如 "MCP Server"）
选择以下权限：
- Account: Read
- Repositories: Read, Write
- Pull requests: Read, Write
点击 "Create"
重要：立即复制生成的密码（之后将无法再次查看！）

运行设置脚本

node scripts/setup-auth.js

这将引导您完成身份验证设置过程。

配置

将服务器添加到您的 MCP 设置文件中（通常位于 ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

替换：

/absolute/path/to/bitbucket-mcp-server 为此目录的实际路径
your-username 为您的 Bitbucket 用户名（非邮箱）
your-app-password 为您创建的应用密码

对于 Bitbucket Server，请使用：

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Bitbucket Server 用户重要提示：

请使用您的完整邮箱地址作为用户名（例如 "john.doe@company.com"）
这是批准/审查操作正常工作所必需的

工具组过滤

通过将 BITBUCKET_TOOL_GROUPS 设置为逗号分隔的组名列表，可以减少每次请求发送给 LLM 的工具数量。只有列出组中的工具才会被暴露。

可用组

组	工具	平台
`pr_core`	`get_pull_request`, `list_pull_requests`, `create_pull_request`, `update_pull_request`, `merge_pull_request`, `decline_pull_request`	两者
`pr_comments`	`add_comment`, `delete_comment`	两者
`pr_review`	`get_pull_request_diff`, `set_pr_approval`, `set_review_status`	两者
`pr_tasks`	`list_pr_tasks`, `create_pr_task`, `update_pr_task`, `set_pr_task_status`, `delete_pr_task`, `convert_pr_item`	仅限 Server
`commits`	`list_pr_commits`, `list_branch_commits`, `get_commit_detail`	两者
`branches`	`list_branches`, `get_branch`, `delete_branch`	两者
`files`	`list_directory_content`, `get_file_content`, `search_files`	两者
`search`	`search_code`, `search_repositories`	仅限 Server
`discovery`	`list_projects`, `list_repositories`	两者

示例预设

PR 审查工作流 (~2,100 tokens)：

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_review,files"
}

完整 PR 管理 (~3,500 tokens)：

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_comments,pr_review,pr_tasks"
}

仅代码探索 (~1,400 tokens)：

"env": {
  "BITBUCKET_TOOL_GROUPS": "files,search,discovery"
}

当未设置 BITBUCKET_TOOL_GROUPS 时，所有适用的工具都会被暴露（默认行为）。无论此设置如何，Bitbucket Cloud 用户始终会自动隐藏仅限 Server 的工具。

使用方法

配置完成后，您可以使用以下可用工具：

获取拉取请求

{
  "tool": "get_pull_request",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

返回有关拉取请求的详细信息，包括：

标题和描述
作者和审查者
源分支和目标分支
批准状态
Web UI 和差异对比链接
合并提交详情（当 PR 已合并时）：
- merge_commit_hash: 合并提交的哈希值
- merged_by: 执行合并的人员
- merged_at: 合并发生的时间
- merge_commit_message: 合并提交消息
带有嵌套回复的活跃评论（需要关注的未解决评论）：
- active_comments: 活跃评论数组（最多 20 条最近的顶级评论）
  - 评论文本和作者
  - 创建日期
  - 是否为行内评论（包含文件路径和行号）
  - 嵌套回复（针对 Bitbucket Server）：
    - replies: 具有相同结构的回复评论数组
    - 回复可以多层嵌套
  - 父级引用（针对 Bitbucket Cloud）：
    - parent_id: 回复的父评论 ID
- active_comment_count: 未解决评论的总数（包括嵌套回复）
- total_comment_count: 所有评论的总数（包括已解决和回复）
文件变更：
- file_changes: PR 中修改的所有文件的数组
  - 文件路径
  - 状态（添加、修改、删除或重命名）
  - 旧路径（针对重命名文件）
- file_changes_summary: 汇总统计信息
  - 总变更文件数
以及更多...

搜索代码

在 Bitbucket 仓库中搜索代码（目前仅支持 Bitbucket Server）：

// Search in a specific repository
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "search_query": "TODO",
    "limit": 50
  }
}

// Search across all repositories in a workspace
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "search_query": "deprecated",
    "file_pattern": "*.java",  // Optional: filter by file pattern
    "limit": 100
  }
}

// Search with file pattern filtering
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "frontend-app",
    "search_query": "useState",
    "file_pattern": "*.tsx",  // Only search in .tsx files
    "start": 0,
    "limit": 25
  }
}

返回搜索结果，包含：

文件路径和名称
仓库和项目信息
匹配行，包含：
- 行号
- 完整行内容
- 显示精确匹配的高亮片段
分页信息

示例响应：

{
  "message": "Code search completed successfully",
  "workspace": "PROJ",
  "repository": "my-repo",
  "search_query": "TODO",
  "results": [
    {
      "file_path": "src/utils/helper.js",
      "file_name": "helper.js",
      "repository": "my-repo",
      "project": "PROJ",
      "matches": [
        {
          "line_number": 42,
          "line_content": "    // TODO: Implement error handling",
          "highlighted_segments": [
            { "text": "    // ", "is_match": false },
            { "text": "TODO", "is_match": true },
            { "text": ": Implement error handling", "is_match": false }
          ]
        }
      ]
    }
  ],
  "total_count": 15,
  "start": 0,
  "limit": 50,
  "has_more": false
}

注意：此工具目前仅适用于 Bitbucket Server。Bitbucket Cloud 支持计划在未来版本中发布。

列出拉取请求

{
  "tool": "list_pull_requests",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "state": "OPEN",  // Optional: OPEN, MERGED, DECLINED, ALL (default: OPEN)
    "author": "username",  // Optional: filter by author (see note below)
    "limit": 25,  // Optional: max results per page (default: 25)
    "start": 0  // Optional: pagination start index (default: 0)
  }
}

返回分页的拉取请求列表，包含：

与 get_pull_request 相同详情的拉取请求数组
匹配 PR 的总数
分页信息 (has_more, next_start)

关于作者过滤器的说明：

对于 Bitbucket Cloud：使用用户名（例如 "johndoe"）
对于 Bitbucket Server：使用完整邮箱地址（例如 "john.doe@company.com"）

创建拉取请求

{
  "tool": "create_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "title": "Add new feature",
    "source_branch": "feature/new-feature",
    "destination_branch": "main",
    "description": "This PR adds a new feature...",  // Optional
    "reviewers": ["john.doe", "jane.smith"],  // Optional
    "close_source_branch": true  // Optional (default: false)
  }
}

更新拉取请求

{
  "tool": "update_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "title": "Updated title",  // Optional
    "description": "Updated description",  // Optional
    "destination_branch": "develop",  // Optional
    "reviewers": ["new.reviewer"]  // Optional - see note below
  }
}

关于审查者的重要说明：

在更新 PR 而不指定 reviewers 参数时，现有的审查者及其批准状态将被保留
当提供 reviewers 参数时：
- 审查者列表将被新列表替换
- 对于 PR 上已存在的审查者，其批准状态将被保留
- 新审查者将被添加，且没有批准状态
这可以防止在您只想更新 PR 描述或标题时意外移除审查者

添加评论

向拉取请求添加评论，可以是常规评论，也可以是针对特定代码的行内评论：

// General comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Great work on this PR!"
  }
}

// Inline comment on specific line
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this into a separate function",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT"  // ADDED, REMOVED, or CONTEXT
  }
}

// Reply to existing comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "I agree with this suggestion",
    "parent_comment_id": 456
  }
}

// Add comment with code suggestion (single line)
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive.",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT",
    "suggestion": "const userAuthenticationToken = token;"
  }
}

// Add comment with multi-line code suggestion
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This function could be simplified using array methods.",
    "file_path": "src/utils/calculations.js",
    "line_number": 50,
    "suggestion_end_line": 55,
    "line_type": "CONTEXT",
    "suggestion": "function calculateTotal(items) {\n  return items.reduce((sum, item) => sum + item.price, 0);\n}"
  }
}

建议功能使用 GitHub 风格的 markdown 建议块格式化评论，Bitbucket 可以渲染这些块。添加建议时：

suggestion 是必需的，包含替换代码
使用建议时，file_path 和 line_number 是必需的
suggestion_end_line 是可选的，用于多行建议（默认为 line_number）
评论将使用 ````suggestion` markdown 块进行格式化，该块可能在 Bitbucket UI 中适用

使用代码片段代替行号

add_comment 工具现在支持使用代码片段自动查找行号。当 AI 工具分析差异且难以确定精确行号时，这特别有用：

// Add comment using code snippet
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive",
    "file_path": "src/components/Button.res",
    "code_snippet": "let isDisabled = false",
    "search_context": {
      "before": ["let onClick = () => {"],
      "after": ["setLoading(true)"]
    }
  }
}

// Handle multiple matches with strategy
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this",
    "file_path": "src/utils/helpers.js",
    "code_snippet": "return result;",
    "search_context": {
      "before": ["const result = calculate();"],
      "after": ["}"]
    },
    "match_strategy": "best"  // Auto-select highest confidence match
  }
}

代码片段参数：

code_snippet: 要查找的精确代码行（line_number 的替代方案）
search_context: 用于消除多个匹配项歧义的可选上下文
- before: 目标行之前应出现的行数组
- after: 目标行之后应出现的行数组
match_strategy: 如何处理多个匹配项
- "strict" (默认): 失败并报错，显示所有匹配项
- "best": 自动选择置信度最高的匹配项

多个匹配项的错误响应（严格模式）：

{
  "error": {
    "code": "MULTIPLE_MATCHES_FOUND",
    "message": "Code snippet 'return result;' found in 3 locations",
    "occurrences": [
      {
        "line_number": 42,
        "file_path": "src/utils/helpers.js",
        "preview": "  const result = calculate();\n> return result;\n}",
        "confidence": 0.9,
        "line_type": "ADDED"
      },
      // ... more matches
    ],
    "suggestion": "To resolve, either:\n1. Add more context...\n2. Use match_strategy: 'best'...\n3. Use line_number directly"
  }
}

此功能特别适用于：

分析差异的 AI 驱动代码审查工具
基于代码模式自动添加评论的脚本
避免在大差异中混淆行号

关于评论回复的说明：

使用 parent_comment_id 回复任何评论（常规或行内）
在 get_pull_request 响应中：
- Bitbucket Server 显示嵌套在 replies 数组中的回复
- Bitbucket Cloud 显示回复评论的 parent_id 字段
您可以回复回复，创建嵌套对话

关于行内评论的说明：

file_path: 差异中显示的文件路径
line_number: 差异中显示的行号
line_type:
- ADDED - 针对新添加的行（差异中为绿色）
- REMOVED - 针对删除的行（差异中为红色）
- CONTEXT - 针对未更改的上下文行

添加评论 - 完整使用指南

add_comment 工具支持多种场景。以下是何时以及如何使用每种方法：

1. 常规 PR 评论（无文件/行号）

使用场景：对 PR 进行整体反馈
必需参数：仅 comment_text
示例："LGTM!", "请更新文档"

2. 回复现有评论

使用场景：继续对话线程
必需参数：comment_text, parent_comment_id
适用于常规和行内评论回复

3. 带行号的行内评论

使用场景：您从差异中知道确切的行号
必需参数：comment_text, file_path, line_number
可选：line_type (默认为 CONTEXT)

4. 带代码片段的行内评论

使用场景：您有代码但没有行号（AI 工具常见）
必需参数：comment_text, file_path, code_snippet
工具将自动查找行号
如果代码多次出现，请添加 search_context
当存在多个匹配项时，使用 match_strategy: "best" 自动选择

5. 代码建议

Bitbucket MCP Server

Bitbucket MCP 服务器

功能特性

可用工具 (共 29 个)

PR 核心 (`pr_core`)

PR 评论 (`pr_comments`)

代码审查 (`pr_review`)

PR 任务 — 仅限 Bitbucket Server (`pr_tasks`)

提交 (`commits`)

分支 (`branches`)

文件 (`files`)

搜索 — 仅限 Bitbucket Server (`search`)

发现 (`discovery`)

Token 优化

安装

使用 npx (推荐)

从源码安装

身份验证设置

创建应用密码

运行设置脚本

配置

工具组过滤

可用组

示例预设

使用方法

获取拉取请求

搜索代码

列出拉取请求

创建拉取请求

更新拉取请求

添加评论

使用代码片段代替行号

添加评论 - 完整使用指南

Resources

Looking for Admin?

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API

Bitbucket MCP 服务器

功能特性

可用工具 (共 29 个)

PR 核心 (pr_core)

PR 评论 (pr_comments)

代码审查 (pr_review)

PR 任务 — 仅限 Bitbucket Server (pr_tasks)

提交 (commits)

分支 (branches)

文件 (files)

搜索 — 仅限 Bitbucket Server (search)

发现 (discovery)

Token 优化

安装

使用 npx (推荐)

从源码安装

身份验证设置

创建应用密码

运行设置脚本

配置

工具组过滤

可用组

示例预设

使用方法

获取拉取请求

搜索代码

列出拉取请求

创建拉取请求

更新拉取请求

添加评论

使用代码片段代替行号

添加评论 - 完整使用指南

Resources

Looking for Admin?

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API

PR 核心 (`pr_core`)

PR 评论 (`pr_comments`)

代码审查 (`pr_review`)

PR 任务 — 仅限 Bitbucket Server (`pr_tasks`)

提交 (`commits`)

分支 (`branches`)

文件 (`files`)

搜索 — 仅限 Bitbucket Server (`search`)

发现 (`discovery`)