微信扫一扫README
🚀 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 要安装哪个包。
其他安装方法
| 模式 | 命令 | 适用场景 |
|------|---------|----------|
| 全局 pip 安装 | pip install bitbucket-mcp-py | 简单、持久的安装 |
| 本地开发 | 在项目目录中执行 pip install -e . | 为项目做贡献 |
| Docker 安装 | 请参阅 Docker 部分 | 基于容器的工作流 |
2. 配置凭证
设置以下环境变量（也可以使用 .env 文件 — 请参阅 凭证）：
| 变量 | 描述 |
|----------|-------------|
| BITBUCKET_USERNAME | 你的 Bitbucket 邮箱 |
| BITBUCKET_TOKEN | 你的 Bitbucket API 令牌 |
| BITBUCKET_WORKSPACE | 你的工作区 slug |
获取你的 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
其他安装方式
| 模式 | 命令 | 适用场景 |
|------|---------|----------|
| 全局 pip 安装 | pip install bitbucket-mcp-py | 简单、持久的安装 |
| 本地开发 | 在项目目录中执行 pip install -e . | 为项目做贡献 |
| Docker 安装 | 请参阅 Docker 部分 | 基于容器的工作流 |
💻 使用示例
基础用法
在配置 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"
}
}
}
}
📚 详细文档
可用工具
| 类别 | 工具 |
|----------|-------|
| 代码仓库 | list_repositories, get_repository |
| 拉取请求 | 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 |
| 构建/持续集成 | 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_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 |
默认禁用：
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
回退链（优先匹配）：
BITBUCKET_TOOLS_CONFIG环境变量- 内置的
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 框架