Bitbucket MCP

Bitbucket MCP

用于集成 Bitbucket Cloud 和 Server API 的模型上下文协议（MCP）服务。此 MCP 服务可让 Cursor 等 AI 助手与您的 Bitbucket 仓库、拉取请求及其他资源交互。

安全第一

这是一个安全可靠的软件包——不使用任何 DELETE 操作，因此没有数据丢失风险。 每个拉取请求都会通过 CodeQL 分析，以确保代码安全。

概览

查看官方 npm 软件包 此服务实现了模型上下文协议标准，为 AI 助手提供对 Bitbucket 数据和操作的访问权限。它包含以下工具：

• 列出和获取仓库
• 获取仓库详情
• 获取拉取请求
• 以及更多……

安装

-- 应大家的要求，基于我们在许多情况下的观察，"BITBUCKET_USERNAME" 通常是您的邮箱地址

使用 NPX（推荐）

使用此 MCP 服务最简单的方法是通过 NPX 运行，无需全局安装：

# Option A (recommended): API URL + explicit workspace
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx -y bitbucket-mcp@latest

# Option B (legacy-compatible): web URL only; workspace is auto-extracted
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx -y bitbucket-mcp@latest

手动安装

或者，您可以将其全局安装，或作为项目的一部分安装：

# Install globally
npm install -g bitbucket-mcp

# Or install in your project
npm install bitbucket-mcp

然后运行：

# If installed globally (Option A)
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp

# If installed globally (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp

# If installed in your project (Option A)
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx bitbucket-mcp

# If installed in your project (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx bitbucket-mcp

配置

环境变量

使用以下环境变量配置服务：

Variable	Description	Required
BITBUCKET_URL	Bitbucket API 基础 URL。默认值为 https://api.bitbucket.org/2.0	No
BITBUCKET_USERNAME	您的 Bitbucket 用户名	Yes*
BITBUCKET_PASSWORD	您的 Bitbucket 应用密码	Yes*
BITBUCKET_TOKEN	您的 Bitbucket 访问令牌（可替代用户名/密码）	No
BITBUCKET_WORKSPACE	要使用的默认工作区。如果省略且 BITBUCKET_URL 中包含工作区，则自动设置	No
BITBUCKET_ENABLE_DANGEROUS	设置为 true 以启用危险工具（例如删除操作）。默认：禁用	No
BITBUCKET_LOG_DISABLE	设置为 true/1 时禁用文件日志	No
BITBUCKET_LOG_FILE	指定日志文件的绝对路径	No
BITBUCKET_LOG_DIR	存储日志的目录（默认为操作系统特定的应用日志目录）	No
BITBUCKET_LOG_PER_CWD	设置为 true 时，将日志存放在按工作目录划分的子文件夹中	No

必须提供 BITBUCKET_TOKEN，或同时提供 BITBUCKET_USERNAME 和 BITBUCKET_PASSWORD。

创建 Bitbucket 应用密码

1. 登录您的 Bitbucket 账户
2. 前往个人设置 > 应用密码
3. 创建具有以下权限的新应用密码：
   • 仓库：读取
   • 拉取请求：读取、写入
   • Pipelines：读取（管道操作所必需）
4. 复制生成的密码，并将其用作 BITBUCKET_PASSWORD 环境变量

故障排除

401 身份验证错误

如果遇到 401 身份验证错误，请检查以下事项：

1. 验证应用密码：确保使用的是应用密码，而不是常规 Bitbucket 密码
2. 验证应用密码权限：应用密码至少需要“Repositories: Read”权限
3. 尝试 API URL 格式：如果仍然遇到 401 错误，请尝试使用直接 API URL 格式：

BITBUCKET_URL="https://api.bitbucket.org/2.0"

1. 测试 API 访问：直接测试 Bitbucket API，验证凭据是否有效：

# Test with curl (replace with your actual values)
curl -u "your-username:your-app-password" \
  "https://api.bitbucket.org/2.0/repositories/your-workspace"

Atlassian API 密钥

1. 将 Atlassian API 密钥填入 BITBUCKET_PASSWORD 变量，而不是 BITBUCKET_TOKEN
2. 将 Bitbucket 邮箱用作 BITBUCKET_USERNAME，而不是常规用户名

请参阅 API 令牌文档了解详情。

获取帮助

如果遇到问题：

1. 查看 Bitbucket REST API 文档了解 API 详情
2. 查看 Bitbucket Cloud 文档获取常规帮助

与 Cursor 集成

要将此 MCP 服务与 Cursor 集成：

1. 打开 Cursor
2. 前往 Settings > Extensions
3. 点击“Model Context Protocol”
4. 添加新的 MCP 配置：

"bitbucket": {
  "command": "npx",
  "env": {
    "BITBUCKET_URL": "https://api.bitbucket.org/2.0",
    "BITBUCKET_WORKSPACE": "your-workspace",
    "BITBUCKET_USERNAME": "your-username",
    "BITBUCKET_PASSWORD": "your-app-password"
  },
  "args": ["-y", "bitbucket-mcp@latest"]
}

1. 保存配置
2. 在 Cursor 中使用“/bitbucket”命令访问 Bitbucket 仓库和拉取请求

在 Cursor 中使用本地构建版本

如果你正在本地开发并想测试更改：

"bitbucket-local": {
  "command": "node",
  "env": {
    "BITBUCKET_URL": "https://api.bitbucket.org/2.0",
    "BITBUCKET_WORKSPACE": "your-workspace",
    "BITBUCKET_USERNAME": "your-username",
    "BITBUCKET_PASSWORD": "your-app-password"
  },
  "args": ["/path/to/your/local/bitbucket-mcp/dist/index.js"]
}

可用工具

此 MCP 服务提供了用于与 Bitbucket 仓库和拉取请求交互的工具。以下是可用操作的完整列表：

分页

除非另有说明，列表工具接受以下可选参数：

• pagelen：每页的条目数（Bitbucket 的 pagelen）。默认值为 10，上限为 100。
• page：要获取的 Bitbucket 页码，从 1 开始。省略时返回第一页。
• all：当值为 true（且未提供 page）时，服务会自动跟随 Bitbucket 的 next 链接，直到获取所有条目或达到 1,000 条的安全上限。
• limit：已弃用的 pagelen 别名，为向后兼容而保留。

使用这些参数可以分页浏览大型集合，避免 CLI 截断。

仓库操作

listRepositories

列出工作区中的仓库。

参数：

• workspace（可选）：Bitbucket 工作区名称
• name（可选）：按部分名称匹配筛选仓库
• 分页中所述的分页控制参数

getRepository

获取特定仓库的详情。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识名

拉取请求操作

getPullRequests

获取仓库的拉取请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识名
• state（可选）：拉取请求状态（OPEN、MERGED、DECLINED、SUPERSEDED）
• 分页中所述的分页控制参数

createPullRequest

创建新的拉取请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识名
• title：拉取请求标题
• description：拉取请求描述
• sourceBranch：源分支名称
• targetBranch：目标分支名称
• reviewers（可选）：审核者用户名列表
• draft（可选）：是否将拉取请求创建为草稿

getPullRequest

获取特定拉取请求的详情。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识名
• pull_request_id：拉取请求 ID
• 分页中所述的分页控制参数
• 分页中所述的分页控制参数
• 分页中所述的分页控制参数
• 分页中所述的分页控制参数

updatePullRequest

更新拉取请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID
• 分页中所述的分页控制参数
• 分页中所述的分页控制参数
• 各种可选更新参数（标题、描述等）

getPullRequestActivity

获取拉取请求的活动日志。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID

approvePullRequest

批准拉取请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID

unapprovePullRequest

取消对拉取请求的批准。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID

declinePullRequest

拒绝拉取请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID
• message（可选）：拒绝原因

mergePullRequest

合并拉取请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID
• message（可选）：合并提交消息
• strategy（可选）：合并策略（merge-commit、squash、fast-forward）

requestChanges

请求修改拉取请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID

removeChangeRequest

移除对拉取请求的修改请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID

createDraftPullRequest

创建新的草稿拉取请求。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• title：拉取请求标题
• description：拉取请求描述
• sourceBranch：源分支名称
• targetBranch：目标分支名称
• reviewers（可选）：审核者用户名列表

**注意：**这等同于调用 createPullRequest 并设置 draft: true。

publishDraftPullRequest

发布草稿拉取请求，使其可以接受审核。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID

convertTodraft

将常规拉取请求转换为草稿状态。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID

拉取请求评论操作

getPullRequestComments

列出拉取请求上的评论。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID

addPullRequestComment

在拉取请求上创建评论（常规评论或行内评论）。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID
• content：Markdown 格式的评论内容
• inline（可选）：用于在特定行上发表评论的行内评论信息

行内评论格式：

inline 参数允许你在拉取请求差异中的特定代码行上发表评论：

{
  "path": "src/file.ts",
  "to": 15, // Line number in NEW version (for added/modified lines)
  "from": 10 // Line number in OLD version (for deleted/modified lines)
}

示例：

• 常规评论：省略 inline 参数即可发表评论
• 评论新增行：仅使用 to 参数
• 评论已删除行：仅使用 from 参数
• 评论已修改行：同时使用 from 和 to 参数

用法：

// General comment
addPullRequestComment(workspace, repo, pr_id, "Great work!");

// Inline comment on new line 25
addPullRequestComment(workspace, repo, pr_id, "Consider error handling here", {
  path: "src/service.ts",
  to: 25,
});

getPullRequestComment

获取拉取请求上的指定评论。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pull_request_id：拉取请求 ID
• comment_id：评论 ID

updatePullRequestComment

更新拉取请求中的评论。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID
• comment_id：评论 ID
• content：更新后的评论内容

deletePullRequestComment

删除拉取请求中的评论。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID
• comment_id：评论 ID

resolveComment

解决拉取请求中的评论讨论串。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID
• comment_id：评论 ID

reopenComment

重新打开拉取请求中已解决的评论讨论串。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID
• comment_id：评论 ID

拉取请求差异操作

getPullRequestDiff

获取拉取请求的差异。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID

getPullRequestDiffStat

获取拉取请求的差异统计信息。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID

getPullRequestPatch

获取拉取请求的补丁。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID

拉取请求任务操作

getPullRequestTasks

列出拉取请求中的任务。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID

createPullRequestTask

在拉取请求中创建任务。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID
• content：任务内容
• comment（可选）：要关联到任务的评论 ID
• pending（可选）：任务是否待处理

getPullRequestTask

获取拉取请求中的指定任务。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID
• task_id：任务 ID

updatePullRequestTask

更新拉取请求中的任务。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID
• task_id：任务 ID
• content（可选）：更新后的任务内容
• state（可选）：更新后的任务状态

deletePullRequestTask

删除拉取请求中的任务。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID
• task_id：任务 ID

其他拉取请求操作

getPullRequestCommits

列出拉取请求中的提交。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID

getPullRequestStatuses

列出拉取请求的提交状态。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• pull_request_id：拉取请求 ID

流水线操作

listPipelineRuns

列出仓库的流水线运行记录。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库 slug
• 分页控制项见分页
• status（可选）：按状态筛选流水线（PENDING、IN_PROGRESS、SUCCESSFUL、FAILED、ERROR、STOPPED）
• target_branch（可选）：按目标分支筛选流水线
• trigger_type（可选）：按触发类型筛选流水线（manual、push、pullrequest、schedule）

getPipelineRun

获取特定流水线运行的详细信息。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pipeline_uuid：流水线 UUID
• 分页中所述的分页控制项

runPipeline

触发新的流水线运行。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• target：流水线目标配置（包含 ref_type、ref_name，以及可选的 commit_hash、selector_type、selector_pattern 的对象）
• variables（可选）：流水线变量数组（包含 key、value 和可选 secured 字段的对象）

stopPipeline

停止正在运行的流水线。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pipeline_uuid：流水线 UUID

getPipelineSteps

列出流水线运行的步骤。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pipeline_uuid：流水线 UUID

getPipelineStep

获取特定流水线步骤的详细信息。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pipeline_uuid：流水线 UUID
• step_uuid：步骤 UUID

getPipelineStepLogs

获取特定流水线步骤的日志。

参数：

• workspace：Bitbucket 工作区名称
• repo_slug：仓库标识
• pipeline_uuid：流水线 UUID
• step_uuid：步骤 UUID

开发

前置条件

• Node.js 18 或更高版本
• npm 或 yarn

设置

# Clone the repository
git clone https://github.com/MatanYemini/bitbucket-mcp.git
cd bitbucket-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

发布到 MCP Registry

准备发布新的服务版本时，请使用官方的 Model Context Protocol 发布指南。仓库已包含该指南要求的所有内容：

1. 构建项目，确保 dist/index.js 是最新版本：

   npm run build
   

2. 生成 Registry 清单（这会读取 package.json 并生成 registry/bitbucket-mcp.manifest.json）：

   npm run registry:manifest
   

3. 按照 publish-server 指南，使用 smithery publish 或该指南推荐的工作流推送清单。

生成的清单包含 CLI 命令（node dist/index.js）、所有已记录的配置选项，以及指向本 README 中设置说明的链接，因此可以直接提交到 MCP Registry。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

链接

• GitHub 仓库
• npm 包
• Model Context Protocol
• Bitbucket REST API 文档
• Bitbucket Cloud 文档