🤖 Bitbucket MCP 服务器教程

🚀 构建与 Bitbucket 工作流集成的 AI 驱动代码审查机器人！

本教程全面介绍了如何构建一个 模型上下文协议 (MCP) 服务器，该服务器连接像 Claude Desktop 和 Cursor 这样的 AI 助手到 Bitbucket 仓库，实现智能代码审查和仓库管理。

⭐ 为什么选择这个教程？

• 🎯 生产就绪：包含 11 个工具和 4 个资源的完整服务器
• 📚 初学者友好：逐步指南，附带可复制粘贴的代码片段
• 🤖 AI 集成：支持 Claude Desktop、Cursor 和任何兼容 MCP 的 AI
• 🔧 实际应用：实际的 PR 审查自动化，而不仅仅是 API 演示
• ⚡ 快速设置：在 10 分钟内启动运行

🎯 你会学到什么

• MCP 基础知识：理解模型上下文协议及其如何连接 AI 助手到外部工具
• 服务器开发：使用 FastMCP 框架构建生产就绪的 MCP 服务器
• API 集成：连接到 Bitbucket 的 REST API 以执行仓库操作
• AI 助手集成：配置 Claude Desktop 和 Cursor 使用你的 MCP 服务器

🚀 该服务器能做什么

将你的 AI 助手转变为一个强大的开发伙伴，能够：

🔧 仓库管理

• 📋 列出并探索具有智能过滤功能的 Bitbucket 仓库
• 📊 获取详细的仓库分析数据和元数据
• 🔍 通过 MCP 资源访问仓库数据以进行复杂查询

🔀 拉取请求自动化

• 📝 自动列出、审查和分析拉取请求
• 💻 获取详细的 PR 信息和完整的代码差异
• ⚡ 使用 AI 推理管理 PR 工作流程（批准、合并、拒绝）
• 💬 添加智能评论并参与协作审查

🤖 AI 驱动的代码审查

• 🔍 使用上下文感知建议分析代码更改
• 📈 识别潜在问题、优化和最佳实践
• 🎯 自动生成有意义的代码审查评论
• 🔄 通过 AI 辅助简化整个审查过程

真实示例："嘿 Claude，审查我的 my-repo 仓库中的最新 PR 并提出改进建议" → 你的 AI 助手获取 PR，分析差异，并提供详细的代码审查反馈！

📋 先决条件

• Python 3.8+（推荐 Python 3.9+）
• Bitbucket 账户，具备 API 访问权限
• 基本 Python 知识（变量、函数、异步/等待）
• 代码编辑器（VS Code、Cursor 或类似工具）

🏗️ 项目结构（教程就绪）

bitbucket-mcp-tutorial/
├── README.md                    # 本综合指南
├── LICENSE                     # MIT 许可证
├── mcp_server.py               # 主 MCP 服务器（简化且有注释）
├── bitbucket_client.py         # Bitbucket API 客户端
├── test_mcp_server.py          # 测试脚本以验证功能
├── config_helper.py            # 生成配置的帮助程序
├── requirements.txt            # Python 依赖项
├── .env.example               # 环境变量模板
└── docs/
    └── ARCHITECTURE.md         # 系统设计和数据流

⚡ 快速开始（5 分钟）

1. 克隆和设置

git clone https://github.com/shibyan-ai-engineer/bitbucket-mcp-tutorial
cd bitbucket-mcp-tutorial
pip install -r requirements.txt

2. 配置环境

cp .env.example .env
# 编辑 .env 文件，填写你的 Bitbucket 凭据

3. 测试服务器

python test_mcp_server.py --quick

4. 配置 AI 助手

python config_helper.py

🔧 详细设置指南

第一步：Python 环境设置

选项 A：使用 pip（适合初学者）

# 创建项目目录
mkdir bitbucket-mcp-tutorial
cd bitbucket-mcp-tutorial

# 安装依赖项
pip install -r requirements.txt

选项 B：使用虚拟环境（适合生产环境）

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# 在 macOS/Linux 上：
source venv/bin/activate
# 在 Windows 上：
venv\\Scripts\\activate

# 安装依赖项
pip install -r requirements.txt

第二步：Bitbucket API 配置

1. 创建应用密码：

   • 前往 Bitbucket → 设置 → 个人设置 → 应用密码
   • 创建新的应用密码，赋予：仓库（读写），拉取请求（读写）
   • 安全保存生成的密码

2. 配置环境变量：

   cp .env.example .env
   

   编辑 .env 文件：

   BITBUCKET_WORKSPACE=你的工作区名称
   BITBUCKET_USERNAME=你的用户名
   BITBUCKET_APP_PASSWORD=你的应用密码
   

第三步：测试你的设置

快速测试（30 秒）：

python test_mcp_server.py --quick

完整测试（2 分钟）：

python test_mcp_server.py

预期输出：

✅ 成功导入 Bitbucket MCP 服务器
✅ 连接成功！
🔧 可用工具（11 个）：[所有工具列表]
📂 可用资源（4 个）：[所有资源列表]
✅ 所有测试均成功完成！

第四步：配置 AI 助手

对于 Claude Desktop：

python config_helper.py --claude

对于 Cursor：

python config_helper.py --cursor

手动配置： 配置助手会显示你需要添加到 AI 助手配置文件中的内容。

🎓 了解代码

核心组件

1. MCP 服务器 (mcp_server.py)

• FastMCP 框架设置
• 用于 Bitbucket 操作的 11 个工具
• 用于数据访问的 4 个资源
• 错误处理和日志记录

2. Bitbucket 客户端 (bitbucket_client.py)

• Bitbucket API 的 HTTP 客户端
• 身份验证处理
• 请求/响应处理

3. 测试脚本 (test_mcp_server.py)

• 综合功能测试
• 性能基准测试
• 集成验证

关键工具解释

# 工具 1：列出仓库
@mcp.tool
async def list_repositories(role: str = "member"):
    """按用户角色列出仓库"""
    # 实现细节...

# 工具 2：获取仓库信息  
@mcp.tool
async def get_repository_info(repo_slug: str):
    """获取详细的仓库信息"""
    # 实现细节...

# 工具 3：列出拉取请求
@mcp.tool
async def list_pull_requests(repo_slug: str, state: str = "OPEN"):
    """带有过滤功能的拉取请求列表"""
    # 实现细节...

资源解释

# 资源 1：仓库列表
@mcp.resource("bitbucket://repositories")
async def get_repositories_resource():
    """提供对仓库数据的访问"""
    # 实现细节...

# 资源 2：特定仓库
@mcp.resource("bitbucket://repo/{repo_slug}")
async def get_repository_resource(repo_slug: str):
    """提供对特定仓库数据的访问"""
    # 实现细节...

🔗 与 AI 助手的集成

Claude Desktop 集成

运行 python config_helper.py --claude 后，将生成的配置添加到：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

示例配置：

{
  "mcpServers": {
    "bitbucket": {
      "command": "python",
      "args": ["/绝对路径/to/mcp_server.py"],
      "env": {
        "BITBUCKET_WORKSPACE": "你的工作区",
        "BITBUCKET_USERNAME": "你的用户名", 
        "BITBUCKET_APP_PASSWORD": "你的应用密码"
      }
    }
  }
}

Cursor 集成

运行 python config_helper.py --cursor 后，将生成的配置添加到 Cursor 设置中。

📊 架构概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI 助手       │    │   MCP 服务器      │    │   Bitbucket     │
│                 │    │                  │    │                 │
│  Claude Desktop │◄──►│  11 个工具       │◄──►│  REST API       │
│     Cursor      │    │  4 个资源        │    │  仓库           │
│                 │    │  FastMCP         │    │  拉取请求       │
└─────────────────┘    └──────────────────┘    └─────────────────┘

数据流

1. 用户请求："审查我的仓库中的最新 PR"
2. AI 助手：解析请求并调用 MCP 工具
3. MCP 服务器：使用 Bitbucket API 处理工具调用
4. Bitbucket API：返回仓库和 PR 数据
5. MCP 服务器：为 AI 助手格式化响应
6. AI 助手：向用户提供智能分析

🛠️ 可用工具及资源

🔧 工具（总计 11 个）

工具	目的	参数
list_repositories	列出用户仓库	role（管理员/成员/贡献者）
get_repository_info	获取仓库详情	repo_slug
list_pull_requests	列出 PR	repo_slug，state
get_pull_request_info	获取 PR 详情	repo_slug，pr_id
get_pull_request_diff	获取 PR 代码差异	repo_slug，pr_id
add_pr_comment	添加 PR 评论	repo_slug，pr_id，content
approve_pr	批准 PR	repo_slug，pr_id
unapprove_pr	移除批准	repo_slug，pr_id
merge_pr	合并 PR	repo_slug，pr_id，merge_strategy
decline_pr	拒绝 PR	repo_slug，pr_id，reason
get_pr_comments	获取 PR 评论	repo_slug，pr_id

📂 资源（总计 4 个）

资源	URI 模式	目的
仓库	bitbucket://repositories	列出所有仓库
特定仓库	bitbucket://repo/{repo_slug}	特定仓库数据
拉取请求	bitbucket://repo/{repo_slug}/pullrequests	仓库的 PR
PR 评论	bitbucket://pr/{repo_slug}/{pr_id}/comments	PR 评论

🎪 实时演示使用示例

🔥 AI 驱动的代码审查实战

👤 你： "审查 my-webapp-project 仓库中的最新 PR"

🤖 AI 助手： 
✅ 查找到 PR #42： "添加用户认证系统"
📊 正在分析 15 个更改文件，342 行增加，89 行删除...

🔍 代码审查总结：
• 强大的 JWT 认证实现
• 潜在的安全问题：需要加强密码验证
• 建议在登录端点添加速率限制
• 缺少中间件的单元测试
• 数据库迁移看起来不错

💬 已发布详细的审查评论，包含具体行建议！

👤 你： "哪些仓库需要紧急关注？"

🤖 AI 助手：
📋 分析了你在工作区中的 12 个仓库：

🚨 高优先级：
• "mobile-app" - 3 个超过两周未解决的 PR
• "api-service" - 依赖项中的安全漏洞

⚠️ 中优先级：  
• "frontend-dashboard" - 1 个大型 PR 等待审核
• "data-pipeline" - 最近没有活动，存在过期的问题

✅ 一切正常：
• "docs-site"，"config-service"，"monitoring-tools"

🎯 仓库探索

👤 你： "我在移动团队工作区中有访问权限的仓库有哪些？"

🤖 AI 助手： 发现了 8 个与 'mobile' 相关的仓库：
📱 "ios-app"（Swift）- 2.3MB，2 天前更新
🤖 "android-app"（Kotlin）- 5.1MB，昨天更新  
🔧 "mobile-api"（Python）- 1.8MB，3 小时前更新
...

🐛 故障排除

常见问题

1. 导入错误

# 错误：ModuleNotFoundError: 没有名为 'fastmcp' 的模块
# 解决方案：安装依赖项
pip install -r requirements.txt

2. 认证错误

# 错误：未经授权 (401)
# 解决方案：检查 .env 文件配置
python config_helper.py --test-auth

3. 服务器连接问题

# 错误：连接被拒绝
# 解决方案：先本地测试服务器
python test_mcp_server.py --quick

调试模式

启用调试日志：

FASTMCP_DEBUG=1 python mcp_server.py

启用测试的详细输出：

python test_mcp_server.py --verbose

📚 学习资源

下一步

1. 探索代码：阅读 mcp_server.py，其中包含教育性注释
2. 尝试实时示例：使用已配置的 AI 助手与仓库互动
3. 扩展功能：为问题、分支或提交添加新工具
4. 自己动手：为其他 API（如 GitHub、GitLab 等）创建 MCP 服务器

额外文档

• docs/ARCHITECTURE.md - 详细的系统设计和技术概述

外部资源

• 模型上下文协议规范
• FastMCP 文档
• Bitbucket REST API 参考

🤝 贡献

欢迎改进此教程项目！如果你发现它有助于构建令人惊叹的 AI 驱动开发工具，请给它一个星⭐！

🎯 贡献领域：

• 🔧 更多 Bitbucket API 集成（问题、部署、流水线）
• 🛡️ 增强的错误处理和重试机制
• 🧪 更全面的测试覆盖
• 📖 文档改进和翻译
• 💡 示例用例和 AI 提示策略
• 🔗 其他 AI 助手的集成指南

加入我们 AI 驱动的开发者社区！ 🚀

📄 许可

MIT 许可证 - 欢迎使用本教程进行学习、教学和构建令人惊叹的 AI 工具！

---

⭐ 喜欢这个项目吗？给它一个星！

🎯 准备革新你的代码审查流程了吗？运行 python test_mcp_server.py --quick 开始吧！

<div align="center">

为 AI 驱动的开发社区打造

⭐ 给这个仓库点赞 • 🐛 报告问题 • 💡 请求功能

</div>