Bitbucket MCP Server

Bitbucket MCP 服务（Python）

将 Claude Code、OpenAI Codex、Cursor、VS Code (GitHub Copilot) 以及任何兼容 MCP 的 AI 助手连接到你的 Bitbucket Cloud 代码库。审查拉取请求、监控流水线并管理代码——一切通过自然语言完成。

功能

• 60+ 个 MCP 工具 — 代码库、拉取请求、评论、任务、差异、流水线（运行时 + 配置）、构建状态、审阅者、草稿 PR、批量审查、问题跟踪器、提交、源码/文件浏览
• MCP 2025 工具注释 — 每个工具都会声明 readOnlyHint / destructiveHint / idempotentHint / openWorldHint，并提供人类可读的标题，因此客户端（Claude Code、Cursor）会自动包含只读工具，并在执行破坏性操作前发出警告
• 精简响应 — 移除 API 冗余信息，降低大模型的 token 用量
• 可配置 — 通过 configs/tools.json 或 BITBUCKET_TOOLS_CONFIG 环境变量启用/禁用工具
• 安全凭证 — 使用环境变量或系统密钥链

快速开始

1. 安装

推荐通过 uvx 运行服务（无需安装，使用隔离环境）：

# Always latest version
uvx --from bitbucket-mcp-py bitbucket-mcp

# Pin a specific version
uvx --from bitbucket-mcp-py==1.8.1 bitbucket-mcp

为什么使用 --from？ PyPI 软件包名为 bitbucket-mcp-py，但命令入口名为 bitbucket-mcp。--from 标志会告诉 uvx 要安装哪个软件包。

其他安装方式

模式	命令	适用场景
pip 全局安装	pip install bitbucket-mcp-py	简单、持久的安装
本地开发	在项目目录中运行 pip install -e .	为项目贡献代码
Docker	参见 Docker 部分	基于容器的工作流

2. 配置凭证

设置以下环境变量——可按上文所示放入 MCP 客户端的 env 块中，或存入系统密钥链（参见凭证）：

变量	说明
BITBUCKET_USERNAME	你的 Bitbucket 邮箱
BITBUCKET_TOKEN	你的 Bitbucket API token
BITBUCKET_WORKSPACE	你的工作区标识

获取 API token： https://id.atlassian.com/manage-profile/security/api-tokens

⚠️ 请使用限定范围的 token，而非全局 token。 创建 token 时，请选择特定范围（例如 Repositories: Read、Pull requests: Read/Write）。未显式指定范围的全局 token 无法与此 MCP 服务配合使用。

3. 配置 AI 助手

Claude Code（推荐）

选项 A — 命令行（最快）：

claude mcp add bitbucket-mcp \
  -e [email protected] \
  -e BITBUCKET_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

选项 B — JSON 配置（~/.claude.json 或项目 .mcp.json）：

{
  "mcpServers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "[email protected]",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

OpenAI Codex

选项 A — 命令行（最快）：

codex mcp add bitbucket-mcp \
  --env [email protected] \
  --env BITBUCKET_TOKEN=your-api-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

选项 B — TOML 配置（~/.codex/config.toml）：

[mcp_servers.bitbucket-mcp]
command = "uvx"
args = ["--from", "bitbucket-mcp-py", "bitbucket-mcp"]
env = { BITBUCKET_USERNAME = "[email protected]", BITBUCKET_TOKEN = "your-api-token", BITBUCKET_WORKSPACE = "your-workspace" }

Cursor

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

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "[email protected]",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

VS Code (GitHub Copilot)

添加到 .vscode/mcp.json（工作区），或 ~/Library/Application Support/Code/User/mcp.json（全局，macOS）：

{
  "servers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "[email protected]",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

可用工具

类别	工具
仓库	list_repositories、get_repository、get_repository_tags
拉取请求	get_pull_requests、get_pull_request、create_pull_request、update_pull_request、approve_pull_request、unapprove_pull_request、request_changes_pull_request、unrequest_changes_pull_request、decline_pull_request、merge_pull_request
评论	get_pull_request_comments、add_pull_request_comment、get_pull_request_comment、update_pull_request_comment、delete_pull_request_comment、resolve_pull_request_comment、reopen_pull_request_comment、get_pull_request_activity
拉取请求任务	get_pull_request_tasks、get_pull_request_task、create_pull_request_task、update_pull_request_task、delete_pull_request_task
差异 / 评审	get_pull_request_diff、get_pull_request_patch、get_pull_request_diffstat、get_pull_request_commits
拉取请求发现	get_pull_requests_pending_review
构建 / CI	get_pull_request_statuses、get_commit_statuses
流水线	list_pipeline_runs、get_pipeline_run、get_pipeline_steps、get_pipeline_step_logs、run_pipeline、stop_pipeline
流水线配置	get_pipeline_config、list_pipeline_variables、get_pipeline_variable、create_pipeline_variable、update_pipeline_variable、delete_pipeline_variable、list_pipeline_schedules、get_pipeline_schedule、list_pipeline_schedule_executions、create_pipeline_schedule、update_pipeline_schedule、delete_pipeline_schedule、list_pipeline_caches、delete_pipeline_cache
评审人	get_effective_default_reviewers、suggest_pull_request_reviewers
草稿拉取请求	create_draft_pull_request、publish_draft_pull_request、convert_pull_request_to_draft
批量评审	submit_pull_request_batch_review
评审摘要	get_pull_request_review_summary
问题	list_issues、get_issue、create_issue、update_issue、delete_issue、get_issue_comments、get_issue_comment、add_issue_comment、update_issue_comment、delete_issue_comment
提交	list_commits、get_commit、get_commit_comments、get_commit_comment、add_commit_comment
源代码	get_file_content、list_directory
部署	list_environments、get_environment、create_environment、delete_environment、list_deployments、get_deployment、list_deployment_variables、create_deployment_variable、update_deployment_variable、delete_deployment_variable
分支限制	list_branch_restrictions、get_branch_restriction、create_branch_restriction、update_branch_restriction、delete_branch_restriction
工作区	list_workspace_members、get_workspace_member、list_workspace_permissions、list_repository_permissions

默认禁用：merge_pull_request（安全）、stop_pipeline（安全）、get_pull_request_patch（git am 格式——对 AI 评审没有用）、convert_pull_request_to_draft（Bitbucket API 不支持）、delete_issue（安全）、delete_issue_comment（安全）、add_commit_comment（写入操作）、create_pipeline_variable / update_pipeline_variable / delete_pipeline_variable（写入操作）、create_pipeline_schedule / update_pipeline_schedule / delete_pipeline_schedule（写入操作）、delete_pipeline_cache（安全）、create_environment / delete_environment / create_deployment_variable / update_deployment_variable / delete_deployment_variable（写入操作）、create_branch_restriction / update_branch_restriction / delete_branch_restriction（写入操作）。在 configs/tools.json 中启用。 治理权限范围 — 分支限制读取工具需要 repository 权限范围（根据仓库配置，可能需要 repository:admin）；写入工具需要 repository:admin。工作区成员/权限工具需要 account 权限范围。/members 端点会列出用户，但不包含每位用户的权限（如需查看角色，请使用 list_workspace_permissions）。

部署权限范围 — 读取工具（list_environments、get_environment、list_deployments、get_deployment、list_deployment_variables）需要 deployment 权限范围；写入工具需要 deployment:write。Bitbucket 不支持在服务端按环境筛选部署（BCLOUD-18729）——请改为按 list_deployments 的 environment 字段筛选。没有 update_environment 工具：Bitbucket 不为环境提供 PUT 接口（仅提供用于锁定的 POST .../changes）。

自定义工具配置

默认情况下，服务会读取软件包内置的 configs/tools.json。无需重新构建，即可在运行时指定自定义文件：

export BITBUCKET_TOOLS_CONFIG=/path/to/my-tools.json

回退链（采用第一个匹配项）：

1. BITBUCKET_TOOLS_CONFIG 环境变量
2. 内置的 configs/tools.json

故障保护行为 — 如果设置了 BITBUCKET_TOOLS_CONFIG，但文件不存在或包含无效 JSON，服务会在启动时引发错误（明确报错，而不是静默忽略覆盖设置）。如果内置默认配置缺失，则启用所有工具。

Token 提示 — get_pull_request_diff 接受可选的 path 参数，可将差异限制为单个文件，从而在大型 PR 中将 Token 用量减少约 95%：

get_pull_request_diff(repo_slug, pull_request_id, path="src/services/myService.ts")

Token 提示 — 默认情况下，get_pipeline_step_logs 仅返回步骤日志末尾的 100 KiB（较长步骤的原始日志可能达到数 MB）。响应包含 truncated 标志；可使用绝对字节范围 start / end 扩大读取范围，或传入 max_bytes=null 以获取完整日志。传入服务容器 UUID 作为 log_uuid，即可读取该服务的日志，而不是构建容器的日志。此端点需要有效的流水线 UUID——如果你只有构建编号，请通过 get_pipeline_run 获取 UUID。

get_pipeline_step_logs(repo_slug, pipeline_uuid="{adab6a1f-...}", step_uuid="{84fc6465-...}")

MCP 提示词

此服务还提供 MCP 提示词——兼容的客户端（Claude Code、Cursor 等）会将其显示为斜杠命令的参数化模板。无需记忆工具名称，只需调用提示词，助手便会为你协调合适的工具。它们会显示在客户端的提示词选择器（prompts/list）中。

提示词	参数	功能
review_pull_request	repo_slug、pull_request_id	完整的 AI 评审：元数据 → 差异统计 → 差异 → 评论 → 任务，然后给出摘要 / 风险 / 质量 / 安全 / 建议
debug_pipeline_failure	repo_slug、pipeline_uuid	诊断流水线失败：运行 → 步骤 → 失败步骤的日志，然后给出根本原因 / 失败步骤 / 错误 / 修复方案
summarize_repository	repo_slug	仓库概览：信息 → 最近提交 → 未关闭的 PR → CI → 问题，然后给出用途 / 活跃情况 / 健康状况 / 贡献者
onboard_reviewer	repo_slug、pull_request_id	帮助新评审者了解情况：PR 背景 → 提交 → 差异 → 评审历史，然后给出背景 / 变更 / 评审进展 / 关注重点

可在 configs/tools.json 顶层的 prompts 键下启用或禁用提示词（与 tools 分开）。

凭据

选项 1：环境变量（推荐）

将它们放在 MCP 客户端配置的 env 块中（如上面的示例所示），或在启动服务的 shell 中导出。

选项 2：系统钥匙串（最安全）

pip install 'bitbucket-mcp-py[keyring]'
python3 -c "import keyring; keyring.set_password('bitbucket-mcp', 'bitbucket_token', 'YOUR_TOKEN')"

关于 .env：服务本身不会读取 .env 文件。.env.example 是供容器使用的模板；容器通过 --env-file .env 或 env_file: 加载它（适用于 Docker、Makefile 和 docker-compose.yml 配置）；使用 uvx 或 python -m src.main 时，请使用选项 1 或 2。

Docker（替代方案）

如果你更愿意在容器中运行服务：

docker build -t bitbucket-mcp-py .
docker run -d --name bitbucket-mcp --env-file .env bitbucket-mcp-py

然后配置 AI 助手使用 docker exec：

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "bitbucket-mcp", "python", "-m", "src.main", "--transport", "stdio"]
    }
  }
}

传输方式

服务默认使用 stdio（本地 MCP 客户端的标准传输方式）。对于网络部署，它也支持 Streamable HTTP（MCP 规范 2025-03-26）：

# Streamable HTTP on localhost:8080
python -m src.main --transport http --host 127.0.0.1 --port 8080

客户端连接到 http://<host>:<port>/mcp（例如 http://localhost:8080/mcp）。

⚠️ --host 默认值为 0.0.0.0，即所有网络接口。未启用 --multi-tenant 时，服务本身没有身份验证：任何能访问该端口的人都可以使用你的 Bitbucket 令牌。除非该端口位于带身份验证的代理之后，否则请绑定到 127.0.0.1。

仍接受 --transport sse（旧版 Server-Sent Events），但已弃用——它会发出 DeprecationWarning。建议使用 --transport http。

无状态 HTTP（水平扩展 / 无服务器）

--stateless 以无服务端会话的方式运行 Streamable HTTP 传输：不使用 Mcp-Session-Id，每个 HTTP 请求都会创建新的传输。负载均衡器后的任意实例都可以处理任意请求——无需粘性会话。

python -m src.main --transport http --host 0.0.0.0 --port 8080 --stateless

⚠️ 默认采用单租户模式。 未启用 --multi-tenant 时，服务会将自身的进程级 Bitbucket 令牌用于每位调用者。请在专用网络中或经过身份验证的反向代理之后部署，或者使用多租户模式，让每位调用者携带自己的凭据。

--stateless 需要 --transport http（在 stdio 和旧版 sse 模式下会被拒绝；后者的应用会忽略此设置）。它还会强制使用单个 JSON 响应，而非 SSE 流，因为边缘 / 无服务器运行时无法保持流式响应处于打开状态——目前无法同时启用无状态模式和流式传输。

两个 HTTP 传输方式都提供了存活探测端点，供负载均衡器使用：

curl http://localhost:8080/healthz    # {"status": "ok"}

在容器中运行——镜像的默认 CMD 会让容器保持空闲，以便通过基于 exec 的 stdio 使用；要启动服务模式，需覆盖命令：

podman run -d --name bitbucket-mcp-http -p 127.0.0.1:8000:8000 --env-file .env bitbucket-mcp-py \
  python -m src.main --transport http --host 0.0.0.0 --port 8000 --stateless

在容器内部必须使用 --host 0.0.0.0；使用 -p 127.0.0.1:8000:8000 可使发布的端口无法从网络访问，因为此单租户服务会向每位调用者使用 .env 中的令牌作出响应。

使用 docker run 时效果相同。镜像开放端口 8000。

环境变量	默认值	用途
BITBUCKET_ALLOWED_HOSTS	（未设置）	以逗号分隔的 Host 允许列表。设置后启用 DNS 重绑定防护。
BITBUCKET_ALLOWED_ORIGINS	（未设置）	以逗号分隔的 Origin 允许列表。
BITBUCKET_MAX_PAGES_HARD_CAP	10	无状态模式下单次工具调用可获取的最大页数。超过该数量时，响应会包含 truncated: true，绝不会静默截断。

两个允许列表必须同时设置：空的 Host 允许列表会拒绝所有请求（421），空的 Origin 允许列表会拒绝所有浏览器客户端（403）。如果只设置其中一个，服务会在启动时拒绝运行，而不是静默地将自己锁在外面。

export BITBUCKET_ALLOWED_HOSTS="mcp.example.com"
export BITBUCKET_ALLOWED_ORIGINS="https://app.example.com"

如果两个允许列表都未设置，则不会启用 DNS 重绑定防护——这适用于通过专用网络或可信代理访问的服务。当服务暴露在真实主机名上时，请立即设置它们。

多租户 HTTP（每个请求使用独立凭据）

默认情况下，HTTP 部署采用单租户模式：每位调用者都使用进程级 Bitbucket 令牌。--multi-tenant 会改变这一点——每个请求都通过 Authorization: Bearer 携带调用者自己的 Bitbucket OAuth 访问令牌，并以该身份运行。服务本身不持有 Bitbucket 凭据。

BITBUCKET_RESOURCE_SERVER_URL=https://mcp.example.com/mcp \
  python -m src.main --transport http --host 0.0.0.0 --port 8080 --stateless --multi-tenant

令牌会通过 GET /2.0/user 验证，该接口会返回调用方的 account_id 和默认工作区；随后，同一令牌会用于下游 API 调用，因此不会存储或映射任何凭据。未通过身份验证的请求会收到 401，并附带指向 /.well-known/oauth-protected-resource/mcp 的 WWW-Authenticate 挑战。由于 Bitbucket 未发布 OAuth 元数据，服务会自行提供 /.well-known/oauth-authorization-server，并指向 Bitbucket 的端点——因此可以将它添加为 claude.ai 自定义连接器（通过 Atlassian 登录登录 Bitbucket）；设置说明、验证内容和剩余风险见 docs/deployment-modes.md。

这样做的好处：

• 隔离 — 每个 (identity, workspace) 使用一个 Bitbucket 客户端；两个调用方绝不会共用同一个客户端，也没有可回退使用的进程令牌。
• workspace=None 表示你的工作区 — 根据调用方的成员身份解析，绝不使用 BITBUCKET_WORKSPACE。如果调用方没有任何工作区成员身份或有多个成员身份，则不存在默认工作区，调用时必须指定工作区。
• 审计跟踪 — 每次调用都会记录到 bitbucket_mcp.audit 日志记录器中，包含工具、account_id 和工作区。绝不记录凭据。
• 更严格的默认设置 — 除非明确启用，否则会拒绝标记为 destructiveHint 的工具。其他写入工具（评论、批准、创建拉取请求、运行流水线……）仍对所有调用方开放：首次部署时可设置 BITBUCKET_MULTITENANT_READ_ONLY=1。

环境变量	默认值	用途
BITBUCKET_RESOURCE_SERVER_URL	（必需）	MCP 端点的公开 URL，例如 https://mcp.example.com/mcp — OAuth 资源标识符
BITBUCKET_OAUTH_ISSUER_URL	（本服务的源站）	公告的授权服务器。留空：服务会自行发布 OAuth 元数据
BITBUCKET_CLIENT_CACHE_SIZE / _TTL	128 / 900	限定每个身份的客户端缓存（LRU + TTL，单位：秒）。TTL 设为 0 时，每个请求都会创建一个新客户端
BITBUCKET_TOKEN_CACHE_SIZE / _TTL	256 / 300	限定缓存的令牌验证结果。TTL 即撤销窗口——设为 0 可验证每个请求
BITBUCKET_MULTITENANT_ALLOW_DESTRUCTIVE	（关闭）	启用 configs/tools.json 中允许的破坏性工具——默认包括 decline_pull_request、delete_pull_request_comment、delete_pull_request_task；其中的 merge、stop_pipeline 和 delete_issue* 仍处于禁用状态
BITBUCKET_MULTITENANT_READ_ONLY	（关闭）	仅提供只读工具
BITBUCKET_MULTITENANT_ALLOWED_WORKSPACES	（未设置：允许任何账户）	以逗号分隔的工作区 slug — 仅允许这些工作区的成员访问，且任何调用都无法访问其他工作区。任何公开端点都应设置此项

与规范不一致：调用方的 Bitbucket 令牌无需进行受众检查即可被接受，并会原样转发至上游；这违反了 MCP 授权规范（2025-11-25）——权衡和剩余风险见 docs/deployment-modes.md。

此模式不支持：Bitbucket Repository/Workspace Access Tokens — 它们未绑定到用户账户，因此无法推导出身份。此类令牌请使用单租户 HTTP 模式。Bearer 令牌需要 TLS：请在服务前端终止 HTTPS。

stdio 不受影响 — 它仍采用环境变量的单用户模式，与上述文档说明完全一致。

三种部署模式的完整对照表及各自的威胁模型，请参见 docs/deployment-modes.md。

Kubernetes（k3s、数据中心、GKE）

每个版本都会发布一个多架构镜像（ghcr.io/lawp09/bitbucket-mcp）和一个 Helm chart（oci://ghcr.io/lawp09/charts/bitbucket-mcp），用于部署多租户 HTTP 模式；publicUrl 是唯一必填项：

helm upgrade --install bitbucket-mcp oci://ghcr.io/lawp09/charts/bitbucket-mcp --version <version> \
  -n bitbucket-mcp --create-namespace --set publicUrl=https://mcp.example.com

Ingress、GKE 和网络策略说明：docs/deployment-kubernetes.md。

开发

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/test_client.py -v

要求

• Python 3.12+
• Bitbucket API 令牌

许可证

MIT

参考资料

• MCP 注册表 — MCP 服务官方注册表
• PyPI 软件包 — Python 软件包
• MCP Python SDK
• Bitbucket API 2.0
• FastMCP 框架