Bitbucket MCP

🚀 Bitbucket MCP 服务器（Python）

将 Claude Code、VS Code（GitHub Copilot）、Cursor 以及任何支持 MCP 的 AI 助手连接到你的 Bitbucket Cloud 代码仓库。通过自然语言审查拉取请求、监控管道并管理你的代码。

🚀 快速开始

1. 安装

推荐使用 uvx（零安装，隔离环境）来运行服务器：

# 始终使用最新版本
uvx --from bitbucket-mcp-py bitbucket-mcp

# 指定特定版本
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 — 命令行界面（最快）：

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"
      }
    }
  }
}

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"
      }
    }
  }
}

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"
      }
    }
  }
}

✨ 主要特性

• 45 个 MCP 工具 — 支持代码仓库、拉取请求、评论、任务、差异比较、管道、构建状态、审查者、草稿拉取请求、批量审查等操作。
• 精简响应 — 去除 API 冗余信息，减少大语言模型（LLM）的令牌使用量。
• 可配置 — 通过 configs/tools.json 或 BITBUCKET_TOOLS_CONFIG 环境变量启用/禁用工具。
• 安全的凭证管理 — 支持使用环境变量或系统钥匙串管理凭证。

📦 安装指南

推荐安装方式

使用 uvx 安装，有两种方式可选：

• 始终使用最新版本：

uvx --from bitbucket-mcp-py bitbucket-mcp

• 指定特定版本：

uvx --from bitbucket-mcp-py==1.8.1 bitbucket-mcp

其他安装方式

💻 使用示例

基础用法

在配置 AI 助手时，以 Claude Code 的命令行配置为例：

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

高级用法

在配置 AI 助手的 JSON 文件时，以 VS Code（GitHub Copilot）为例：

{
  "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 不支持）。可在 configs/tools.json 中启用。

自定义工具配置

默认情况下，服务器读取包中自带的 configs/tools.json。你可以在运行时指向自定义文件，而无需重新构建：

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

回退链（优先匹配）：

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

故障安全行为 — 如果设置了 BITBUCKET_TOOLS_CONFIG 但文件缺失或包含无效 JSON，服务器在启动时会抛出错误（明确失败，而不是默默忽略覆盖）。如果内置默认文件缺失，所有工具将被启用。

💡 令牌提示 — get_pull_request_diff 接受一个可选的 path 参数，用于将差异过滤到单个文件，在大型拉取请求中可减少约 95% 的令牌使用量：

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

凭证管理

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

cp .env.example .env
# 编辑 .env 文件，填入你的凭证

选项 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"]
    }
  }
}

开发

# 安装开发依赖
uv sync --extra dev

# 运行测试
uv run pytest tests/ -v

# 运行特定测试
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 框架