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 冗余信息，降低 LLM 令牌消耗

• 可配置 — 通过 configs/tools.json 或 BITBUCKET_TOOLS_CONFIG 环境变量启用/禁用工具

• 安全凭据 — 环境变量或系统钥匙串

Related MCP server: Bitbucket MCP

快速开始

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 要安装哪个包。

2. 配置凭据

设置以下环境变量（或使用 .env 文件 — 参见 凭据）：

获取您的 API 令牌：https://id.atlassian.com/manage-profile/security/api-tokens

⚠️ 请使用限定范围的令牌，而非全局令牌。 创建令牌时，请选择特定范围（例如 Repositories: Read、Pull requests: Read/Write）。没有明确范围的全局令牌无法与此 MCP 服务器配合使用。

3. 配置您的 AI 助手

Claude Code（推荐）

选项 A — CLI（最快）：

claude mcp add bitbucket-mcp \
  -e BITBUCKET_USERNAME=your-email@example.com \
  -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": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

OpenAI Codex

选项 A — CLI（最快）：

codex mcp add bitbucket-mcp \
  --env BITBUCKET_USERNAME=your-email@example.com \
  --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 = "your-email@example.com", 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": "your-email@example.com",
        "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": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

可用工具

默认禁用：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 上可减少约 95% 的 token 使用量：

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 解析它。

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

MCP 提示

该服务器还公开了 MCP 提示 — 兼容客户端（Claude Code、Cursor 等）将其作为斜杠命令使用的参数化模板。您无需记住工具名称，只需调用提示，助手便会为您编排正确的工具。它们会出现在客户端的提示选择器中（prompts/list）。

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

凭证

选项 1：.env 文件（推荐）

cp .env.example .env
# Edit .env with your credentials

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

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

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 0.0.0.0:8080
python -m src.main --transport http --host 0.0.0.0 --port 8080

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

--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 8000:8000 --env-file .env bitbucket-mcp-py \
  python -m src.main --transport http --host 0.0.0.0 --port 8000 --stateless

与 docker run 完全一致。镜像暴露端口 8000。

两个白名单必须一起设置：空的 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 改变了这一点——每个请求携带调用者自己的 Bitbucket OAuth 访问令牌作为 Authorization: Bearer，并以该身份运行。服务器自身不持有任何 Bitbucket 凭证。

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

令牌通过 GET /2.0/user 验证，该端点返回调用者的 account_id 和默认工作区；同一令牌随后被重用于下游 API 调用，因此不会存储或映射任何凭证。未经身份验证的请求会收到 401，并附带 WWW-Authenticate 挑战，指向 /.well-known/oauth-protected-resource。

这带来的好处：

• 隔离性——每个 (identity, workspace) 对应一个 Bitbucket 客户端；两个调用者永远不会共享一个，也没有进程令牌可回退。

• workspace=None 表示你的工作区——从调用者的成员身份中解析，绝不会从 BITBUCKET_WORKSPACE 获取。如果零个或多个成员身份，则没有默认值，调用必须指明工作区。

• 审计追踪——每次调用都会记录到 bitbucket_mcp.audit 日志器，包含工具、account_id 和工作区。绝不记录凭证。

• 更严格的默认值——标记为 destructiveHint 的工具在未显式启用时会被拒绝。

此模式不支持：Bitbucket 仓库/工作区访问令牌——它们未绑定到用户账户，因此无法推导出身份。请使用单租户 HTTP 来处理。Bearer 令牌需要 TLS：在服务器前终止 HTTPS。

stdio 不受影响——它保持单用户模式，使用环境变量，与上述文档完全一致。

详见 docs/deployment-modes.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 Registry —— 官方 MCP 服务器注册表

• PyPI Package —— Python 包

• MCP Python SDK

• Bitbucket API 2.0

• FastMCP Framework