Bitbucket MCP Server 是一个基于模型上下文协议(MCP)的服务器,它提供了与 Bitbucket API 交互的工具,同时支持 Bitbucket Cloud 和 Bitbucket Server。
本 MCP 服务器提供了丰富的工具,用于与 Bitbucket API 进行交互。你可以按照以下步骤进行安装和配置,从而使用这些工具。
get_pull_request - 获取拉取请求的详细信息list_pull_requests - 按筛选条件(状态、作者、分页)列出拉取请求create_pull_request - 创建新的拉取请求update_pull_request - 更新拉取请求的详细信息(标题、描述、审核人、目标分支)add_comment - 为拉取请求添加评论(支持回复)merge_pull_request - 以各种策略合并拉取请求list_pr_commits - 列出属于拉取请求的所有提交delete_branch - 合并后删除分支list_branches - 按筛选条件和分页列出分支delete_branch - 删除分支(进行保护检查)get_branch - 获取详细的分支信息,包括关联的 PRlist_branch_commits - 按高级筛选条件列出分支中的提交list_directory_content - 列出存储库路径中的文件和目录get_file_content - 获取文件内容,对大文件进行智能截断get_pull_request_diff - 获取拉取请求的差异/更改approve_pull_request - 批准拉取请求unapprove_pull_request - 撤销对拉取请求的批准request_changes - 请求对拉取请求进行更改remove_requested_changes - 撤销对拉取请求的更改请求使用 npx 直接使用此 MCP 服务器是最简单的方法:
{
"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
npm run build
此服务器使用 Bitbucket 应用密码进行身份验证。
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 用户注意事项:
{
"tool": "get_pull_request",
"arguments": {
"workspace": "PROJ", // 必需 - 你的项目密钥
"repository": "my-repo",
"pull_request_id": 123
}
}
返回拉取请求的详细信息,包括:
merge_commit_hash:合并提交的哈希值merged_by:执行合并的人merged_at:合并发生的时间merge_commit_message:合并提交消息active_comments:活动评论数组(最多 20 条最近的顶级评论)
replies:具有相同结构的回复评论数组parent_id:回复评论的父评论 IDactive_comment_count:未解决评论的总数(包括嵌套回复)total_comment_count:所有评论的总数(包括已解决和回复)file_changes:PR 中修改的所有文件的数组
file_changes_summary:摘要统计信息
{
"tool": "list_pull_requests",
"arguments": {
"workspace": "PROJ", // 必需 - 你的项目密钥
"repository": "my-repo",
"state": "OPEN", // 可选: OPEN, MERGED, DECLINED, ALL (默认: OPEN)
"author": "username", // 可选: 按作者筛选 (见下面的注释)
"limit": 25, // 可选: 每页的最大结果数 (默认: 25)
"start": 0 // 可选: 分页起始索引 (默认: 0)
}
}
返回分页的拉取请求列表,包含:
get_pull_request 相同详细信息的拉取请求数组作者筛选注意事项:
{
"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...", // 可选
"reviewers": ["john.doe", "jane.smith"], // 可选
"close_source_branch": true // 可选 (默认: false)
}
}
{
"tool": "update_pull_request",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"title": "Updated title", // 可选
"description": "Updated description", // 可选
"destination_branch": "develop", // 可选
"reviewers": ["new.reviewer"] // 可选 - 见下面的注释
}
}
审核人重要说明:
reviewers 参数,现有审核人和他们的批准状态将被保留reviewers 参数时:
为拉取请求添加评论,可以是一般评论或特定代码行的内联评论:
// 一般评论
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "Great work on this PR!"
}
}
// 特定行的内联评论
{
"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
}
}
// 回复现有评论
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "I agree with this suggestion",
"parent_comment_id": 456
}
}
// 添加带有代码建议的评论(单行)
{
"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;"
}
}
// 添加带有多行代码建议的评论
{
"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)add_comment 工具现在支持使用代码片段自动查找行号。这在 AI 工具分析差异时特别有用,因为它们可能难以确定确切的行号:
// 使用代码片段添加评论
{
"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)"]
}
}
}
// 使用策略处理多个匹配项
{
"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" // 自动选择最高置信度匹配
}
}
代码片段参数:
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"
},
// ... 更多匹配项
],
"suggestion": "To resolve, either:\n1. Add more context...\n2. Use match_strategy: 'best'...\n3. Use line_number directly"
}
}
此功能对于以下情况特别有用:
评论回复注意事项:
parent_comment_id 回复任何评论(一般或内联)get_pull_request 响应中:
replies 数组中显示嵌套回复parent_id 字段内联评论注意事项:
file_path:差异中显示的文件路径line_number:差异中显示的行号line_type:
ADDED - 对于新添加的行(差异中为绿色)REMOVED - 对于删除的行(差异中为红色)CONTEXT - 对于未更改的上下文行add_comment 工具支持多种场景。以下是何时以及如何使用每种方法:
1. 一般 PR 评论(无文件/行)
comment_text2. 回复现有评论
comment_text,parent_comment_id3. 带行号的内联评论
comment_text,file_path,line_numberline_type(默认为 CONTEXT)4. 带代码片段的内联评论
comment_text,file_path,code_snippetsearch_contextmatch_strategy: "best" 自动选择5. 代码建议
comment_text,file_path,line_number,suggestionsuggestion_end_lineAI/自动化工具的决策流程:
1. 你是否想建议代码更改?
→ 使用带行号的建议
2. 你是否有确切的行号?
→ 直接使用行号
3. 你有代码片段但没有行号吗?
→ 使用代码片段(如有需要添加搜索上下文)
4. 这是关于 PR 的一般评论吗?
→ 仅使用 comment_text
5. 你是否在回复另一条评论?
→ 添加 parent_comment_id
避免常见陷阱:
line_number 和 code_snippet - 选择其一file_path 和 line_number{
"tool": "merge_pull_request",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"merge_strategy": "squash", // 可选: merge-commit, squash, fast-forward
"close_source_branch": true, // 可选
"commit_message": "Custom merge message" // 可选
}
}
{
"tool": "list_branches",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"filter": "feature", // 可选: 按名称模式筛选
"limit": 25, // 可选 (默认: 25)
"start": 0 // 可选: 用于分页 (默认: 0)
}
}
返回分页的分支列表,包含:
{
"tool": "delete_branch",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "feature/old-feature",
"force": false // 可选 (默认: false)
}
}
注意:删除分支需要适当的权限。分支将被永久删除。
{
"tool": "get_branch",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "feature/new-feature",
"include_merged_prs": false // 可选 (默认: false)
}
}
返回全面的分支信息,包括:
include_merged_prs 为 true):
此工具对于以下情况特别有用:
获取特定分支中的所有提交,并具有高级筛选选项:
// 基本用法 - 获取最近的提交
{
"tool": "list_branch_commits",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "feature/new-feature",
"limit": 50 // 可选 (默认: 25)
}
}
// 按日期范围筛选
{
"tool": "list_branch_commits",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "main",
"since": "2025-01-01T00:00:00Z", // ISO 日期字符串
"until": "2025-01-15T23:59:59Z" // ISO 日期字符串
}
}
// 按作者筛选
{
"tool": "list_branch_commits",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "develop",
"author": "john.doe@company.com", // 电子邮件或用户名
"limit": 100
}
}
// 排除合并提交
{
"tool": "list_branch_commits",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "release/v2.0",
"include_merge_commits": false
}
}
// 在提交消息中搜索
{
"tool": "list_branch_commits",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "main",
"search": "bugfix", // 在提交消息中搜索
"limit": 50
}
}
// 组合多个筛选器
{
"tool": "list_branch_commits",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "develop",
"author": "jane.smith@company.com",
"since": "2025-01-01T00:00:00Z",
"include_merge_commits": false,
"search": "feature",
"limit": 100,
"start": 0 // 用于分页
}
}
筛选参数:
since:ISO 日期字符串 - 仅显示此日期之后的提交until:ISO 日期字符串 - 仅显示此日期之前的提交author:按作者电子邮件/用户名筛选include_merge_commits:布尔值,是否包含合并提交(默认:true)search:在提交消息中搜索文本返回详细的提交信息:
{
"branch_name": "feature/new-feature",
"branch_head": "abc123def456", // 最新提交哈希
"commits": [
{
"hash": "abc123def456",
"abbreviated_hash": "abc123d",
"message": "Add new feature implementation",
"author": {
"name": "John Doe",
"email": "john.doe@example.com"
},
"date": "2025-01-03T10:30:00Z",
"parents": ["parent1hash", "parent2hash"],
"is_merge_commit": false
}
// ... 更多提交
],
"total_count": 150,
"start": 0,
"limit": 25,
"has_more": true,
"next_start": 25,
"filters_applied": {
"author": "john.doe@example.com",
"since": "2025-01-01",
"include_merge_commits": false
}
}
此工具对于以下情况特别有用:
获取属于拉取请求的所有提交:
{
"tool": "list_pr_commits",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"limit": 50, // 可选 (默认: 25)
"start": 0 // 可选: 用于分页
}
}
返回 PR 的提交信息:
{
"pull_request_id": 123,
"pull_request_title": "Add awesome feature",
"commits": [
{
"hash": "def456ghi789",
"abbreviated_hash": "def456g",
"message": "Initial implementation",
"author": {
"name": "Jane Smith",
"email": "jane.smith@example.com"
},
"date": "2025-01-02T14:20:00Z",
"parents": ["parent1hash"],
"is_merge_commit": false
}
// ... 更多提交
],
"total_count": 5,
"start": 0,
"limit": 25,
"has_more": false
}
此工具对于以下情况特别有用:
获取拉取请求的差异/更改,并具有可选的筛选功能:
// 获取完整差异(默认行为)
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"context_lines": 5 // 可选 (默认: 3)
}
}
// 排除特定文件类型
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"exclude_patterns": ["*.lock", "*.svg", "node_modules/**", "*.min.js"]
}
}
// 仅包含特定文件类型
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"include_patterns": ["*.res", "*.resi", "src/**/*.js"]
}
}
// 仅获取特定文件的差异
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"file_path": "src/components/Button.res"
}
}
// 组合筛选器
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"include_patterns": ["src/**/*"],
"exclude_patterns": ["*.test.js", "*.spec.js"]
}
}
筛选选项:
include_patterns:要包含的 glob 模式数组(白名单)exclude_patterns:要排除的 glob 模式数组(黑名单)file_path:仅获取特定文件的差异*.js,src/**/*.res,!test/**)响应包含筛选元数据:
{
"message": "Pull request diff retrieved successfully",
"pull_request_id": 123,
"diff": "..filtered diff content..",
"filter_metadata": {
"total_files": 15,
"included_files": 12,
"excluded_files": 3,
"excluded_file_list": ["package-lock.json", "logo.svg", "yarn.lock"],
"filters_applied": {
"exclude_patterns": ["*.lock", "*.svg"]
}
}
}
{
"tool": "approve_pull_request",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123
}
}
{
"tool": "request_changes",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment": "Please address the following issues..." // 可选
}
}
{
"tool": "list_directory_content",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"path": "src/components", // 可选 (默认为根目录)
"branch": "main" // 可选 (默认为默认分支)
}
}
返回目录列表,包含:
{
"tool": "get_file_content",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"file_path": "src/index.ts",
"branch": "main", // 可选 (默认为默认分支)
"start_line": 1, // 可选: 起始行 (基于 1,负数表示从末尾开始)
"line_count": 100, // 可选: 返回的行数
"full_content": false // 可选: 强制获取完整内容 (默认: false)
}
}
智能截断功能:
start_line: -50 获取最后 50 行(尾部功能)full_content: true 或行参数返回文件内容,包含:
示例响应:
// 小文件 - 返回完整内容
{
"file_path": "package.json",
"branch": "main",
"size": 1234,
"encoding": "utf-8",
"content": "{\n \"name\": \"my-project\",\n ...",
"last_modified": {
"commit_id": "abc123",
"author": "John Doe",
"date": "2025-01-21T10:00:00Z"
}
}
// 大文件 - 自动截断
{
"file_path": "src/components/LargeComponent.tsx",
"branch": "main",
"size": 125000,
"encoding": "utf-8",
"content": "... first 500 lines ...",
"line_info": {
"total_lines": 3500,
"returned_lines": {
"start": 1,
"end": 500
},
"truncated": true,
"message": "Showing lines 1-500 of 3500. File size: 122.1KB"
}
}
在实际开发中,你可以根据具体需求组合使用这些工具,以实现更复杂的功能。例如,结合 list_pull_requests 和 get_pull_request_diff 工具,先列出符合条件的拉取请求,再获取特定拉取请求的差异信息,从而进行更细致的代码审查。
本项目使用 Node.js 构建,并使用 TypeScript 进行类型检查,以确保代码的健壮性和可维护性。通过与 Bitbucket API 交互,实现了各种工具的功能。在处理大文件时,采用了智能截断的策略,避免因文件过大导致的性能问题。同时,在身份验证方面,使用 Bitbucket 应用密码,提供了安全可靠的认证方式。
本项目采用 MIT 许可证。