MCP Server for Bitbucket API

Bitbucket MCP 服务

用于执行 Bitbucket API 操作的 MCP 服务。兼容 Claude Code、Claude Desktop、Cursor 和任何兼容 MCP 的客户端。

语言版本

此代码库包含 TypeScript 和 Python 两种实现：

版本	目录	状态	安装方式
TypeScript	/typescript	✅ 推荐（Smithery）	npm install -g mcp-server-bitbucket
Python	/python	✅ 稳定	pipx install mcp-server-bitbucket

注意：Smithery 部署使用 TypeScript 版本。两个版本提供完全相同的功能。

TypeScript 请使用打过补丁的 Node.js 22.23.4 或 24.22.1；Python 请使用 Python 3.11+。 有关 HTTP 请求限制和可复现镜像构建，请参阅安全更新。

功能

• 代码库：获取、创建、删除、列出、更新（移至项目、重命名）
• 拉取请求：创建、获取、列出、合并、批准、拒绝、请求更改、评论、差异
• 流水线：触发、获取状态、列出、查看日志、停止
• 分支：列出、获取
• 项目：列出、获取
• 提交：列出、获取详情、比较分支或查看分支间差异
• 提交状态：获取构建状态、创建状态（CI/CD 集成）
• 部署：列出环境、获取环境详情、部署历史
• Webhook：列出、创建、获取、删除
• 标签：列出、创建、删除
• 分支限制：列出、创建、删除分支保护规则
• 源码浏览：读取文件、列出目录，无需克隆
• 代码库权限：管理用户和群组权限
• 流水线变量：管理 CI/CD 环境变量
• MCP 提示词：可复用的工作流模板（代码审查、发行说明等）
• MCP 资源：可浏览的工作区数据

快速开始

TypeScript（推荐用于 Smithery）

# Install globally
npm install -g mcp-server-bitbucket

# Or run directly with npx
npx mcp-server-bitbucket

Python

# Install with pipx
pipx install mcp-server-bitbucket

# Configure Claude Code
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e [email protected] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

完整安装指南 - 包含 API 令牌创建、权限设置和故障排除。

托管服务

如果你不想自行运行该服务，可以使用部署在 Fronteir AI 上的托管服务。

配置

环境变量

变量	必需	说明
BITBUCKET_WORKSPACE	✅	Bitbucket 工作区 slug
BITBUCKET_EMAIL	✅（基本身份验证）	用于 Basic Auth 的账户邮箱
BITBUCKET_API_TOKEN	✅	Atlassian API 令牌（Basic 身份验证）
BITBUCKET_OAUTH_TOKEN		作为 Authorization: Bearer 发送的访问令牌
BITBUCKET_AUTH_TYPE		强制指定身份验证模式：basic 或 bearer（自动检测）
API_TIMEOUT		请求超时时间（秒，默认：30）
MAX_RETRIES		速率限制时的最大重试次数（默认：3）

认证模式

Bitbucket Cloud 有两类凭据，它们使用的认证方案并不相同：

凭据	请求头	配置
Atlassian API token（ATATT...），关联个人帐户	Authorization: Basic base64(email:token)	BITBUCKET_EMAIL + BITBUCKET_API_TOKEN
工作区 / 项目 / 仓库访问令牌（ATCTT...），由工作区持有	Authorization: Bearer <token>	BITBUCKET_OAUTH_TOKEN

访问令牌使用 Basic auth 时会返回 401，因此服务会自动选择模式：

1. 设置了 BITBUCKET_AUTH_TYPE 时，始终优先使用该值。
2. 否则，如果设置了 BITBUCKET_OAUTH_TOKEN，或者未配置 BITBUCKET_EMAIL，则使用 bearer。
3. 否则使用 basic（个人 API token 的默认模式）。

Bearer 示例 — 公司持有的工作区访问令牌，不涉及个人帐户：

claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_OAUTH_TOKEN=your-workspace-access-token \
  -- npx mcp-server-bitbucket

保护远程服务（OAuth）

stdio 服务在你的计算机上使用你自己的凭据运行，因此无需保护。远程部署则不同：它持有一个共享凭据，并为所有能够访问它的用户提供服务，因此可以通过外部授权服务器（Microsoft Entra ID、Okta、Auth0……）颁发的 bearer token 限制对 /mcp 的访问。

变量	说明
MCP_OAUTH_ISSUER	Token 颁发者，例如 https://login.microsoftonline.com/<tenant>/v2.0
MCP_OAUTH_AUDIENCE	预期的 aud 声明，例如 api://bitbucket-mcp
MCP_OAUTH_JWKS_URI	签名密钥（未指定时根据颁发者推导）
MCP_OAUTH_REQUIRED_SCOPE	Token 必须包含的作用域，例如 mcp.access
MCP_PUBLIC_URL	此服务的公开 URL，作为资源公布

只有同时设置 MCP_OAUTH_ISSUER 和 MCP_OAUTH_AUDIENCE 时，保护功能才会启用，因此不会影响现有部署。设置这两个变量后，服务将：

• 对未经身份验证的 /mcp 请求返回 401，并附带指向 /.well-known/oauth-protected-resource 的 WWW-Authenticate 请求头，以此促使 MCP 客户端启动 OAuth 流程；
• 提供该元数据文档（RFC 9728），其中注明授权服务器；
• 验证每个请求的 JWT — 使用颁发者的 JWKS 验证签名，并检查 iss、aud 和过期时间 — 如果有效 Token 缺少所需作用域，则返回 403 insufficient_scope；
• 保持 /health 开放，以便平台探测继续正常工作。

请注意，此功能能做什么、不能做什么：它控制谁可以使用该服务。调用仍会使用服务自己的凭据访问 Bitbucket，因此无法将操作归属到具体用户。

Claude Code CLI

# TypeScript version
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e [email protected] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- npx mcp-server-bitbucket

# Python version
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e [email protected] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

Cursor IDE

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["mcp-server-bitbucket"],
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_EMAIL": "[email protected]",
        "BITBUCKET_API_TOKEN": "your-api-token"
      }
    }
  }
}

可用工具（共 58 个）

仓库

工具	说明
list_repositories	列出并搜索仓库
get_repository	获取仓库详情
create_repository	创建新仓库
delete_repository	删除仓库
update_repository	更新仓库设置

拉取请求

工具	说明
list_pull_requests	列出 PR
get_pull_request	获取 PR 详情
create_pull_request	创建新的 PR
merge_pull_request	合并 PR
approve_pr	批准 PR
unapprove_pr	撤销批准
request_changes_pr	请求修改
decline_pr	拒绝 PR
list_pr_comments	列出评论
add_pr_comment	添加评论
get_pr_diff	获取差异

流水线

工具	描述
list_pipelines	列出最近的运行记录
get_pipeline	获取状态
get_pipeline_logs	查看日志
trigger_pipeline	触发一次运行（支持自定义流水线和提交触发）
stop_pipeline	停止流水线
list_pipeline_variables	列出变量
get_pipeline_variable	获取变量
create_pipeline_variable	创建变量
update_pipeline_variable	更新变量
delete_pipeline_variable	删除变量

trigger_pipeline 参数

参数	类型	描述
repo_slug	string	仓库 slug（必填）
branch	string	要在其上运行的分支（默认：main）。不能与 commit 同时使用
commit	string	要在其上运行的提交哈希。不能与 branch 同时使用
custom_pipeline	string	bitbucket-pipelines.yml 中 custom: 部分的名称
variables	array	变量，格式为 [{key, value, secured?}]

示例：

# Default pipeline on main
trigger_pipeline(repo_slug="my-repo")

# Custom pipeline
trigger_pipeline(repo_slug="my-repo", custom_pipeline="deploy-staging")

# Custom pipeline on specific commit with variables
trigger_pipeline(
    repo_slug="my-repo",
    commit="abc123def",
    custom_pipeline="deploy-prod",
    variables=[
        {"key": "ENV", "value": "production"},
        {"key": "SECRET", "value": "xxx", "secured": True}
    ]
)

分支、提交、标签

工具	描述
list_branches	列出分支
get_branch	获取分支详情
list_commits	列出提交
get_commit	获取提交详情
compare_commits	比较分支
get_commit_statuses	获取构建状态
create_commit_status	报告 CI 状态
list_tags	列出标签
create_tag	创建标签
delete_tag	删除标签

还有更多……

• 部署：list_environments、get_environment、list_deployment_history
• Webhook：list_webhooks、create_webhook、get_webhook、delete_webhook
• 分支限制：list_branch_restrictions、create_branch_restriction、delete_branch_restriction
• 源码浏览：get_file_content、list_directory
• 权限：用户和群组权限管理（8 个工具）
• 项目：list_projects、get_project

MCP 提示词

可重复使用的工作流模板：

提示词	描述
code_review	全面的 PR 代码审查
release_notes	生成版本之间的变更日志
pipeline_debug	调试失败的 CI/CD 流水线
repo_summary	完整的仓库状态概览

MCP 资源

可浏览的工作区数据：

资源 URI	描述
bitbucket://repositories	列出所有仓库
bitbucket://repositories/{repo}	仓库详情
bitbucket://repositories/{repo}/branches	分支列表
bitbucket://repositories/{repo}/pull-requests	未关闭的 PR
bitbucket://projects	列出所有项目

开发

TypeScript

cd typescript
npm install
npm run build
npm run dev  # Watch mode

Python

cd python
uv sync
uv run python -m src.server

创建 Bitbucket API 令牌

1. 前往 Bitbucket 中的仓库
2. 导航到 仓库设置 > 访问令牌
3. 点击 创建仓库访问令牌
4. 选择权限：
   • 仓库：读取、写入、管理、删除
   • 拉取请求：读取、写入
   • 流水线：读取、写入
5. 立即复制令牌

在工作中使用

如果你的团队正在公司 Bitbucket 上运行此工具，我很想了解情况。这会影响后续开发内容，而且来自真实部署的问题会优先处理。

我会承接两类相关工作：

• 为尚无 MCP 服务的内部系统开发 MCP 服务。 与此服务结构相同，但面向你们自己的 API。
• 帮助 MCP 部署通过安全审查——包括作用域、令牌处理以及自行托管传输层。

请提交 issue，或写信至 [email protected]。

作者

由 Javier Aguilar 构建并维护——一位从事 Agent 系统和 MCP 集成工作的 AI 工程师。关于此服务构建过程及原因的文章见 此处。

许可证

MIT