MCP Bitbucket Python 🦊

MCP Bitbucket Python 🦊

一个用于集成 Bitbucket 的 MCP 服务 Python 实现。MCP（模型上下文协议）支持 AI 应用安全地在本地访问工具。该服务与 AI 应用运行在同一台机器上。

安装

# Install the server locally
git clone https://github.com/kallows/mcp-bitbucket.git
cd mcp-bitbucket

# Install dependencies using uv (recommended) or pip
uv install
# or
pip install -e .

可用工具

此 MCP 服务提供以下 Bitbucket 集成工具：

• bb_create_repository：创建新的 Bitbucket 仓库

  • 必填：name（仓库名称）
  • 可选：description、workspace（默认为 kallows）、project_key、is_private（默认为 true）、has_issues（默认为 true）

• bb_create_branch：在仓库中创建新分支

  • 必填：repo_slug、branch（新分支的名称）
  • 可选：workspace（默认为 kallows）、start_point（默认为 main）

• bb_delete_repository：删除 Bitbucket 仓库

  • 必填：repo_slug
  • 可选：workspace（默认为 kallows）

• bb_read_file：读取仓库中的文件

  • 必填：repo_slug、path（仓库中的文件路径）
  • 可选：workspace（默认为 kallows）、branch（默认为 main/master）

• bb_write_file：在仓库中创建或更新文件

  • 必填：repo_slug、path、content
  • 可选：workspace（默认为 kallows）、branch（默认为 main）、message（提交消息）

• bb_create_issue：在仓库中创建 issue

  • 必填：repo_slug、title、content
  • 可选：workspace（默认为 kallows）、kind（bug/enhancement/proposal/task）、priority（trivial/minor/major/critical/blocker）

• bb_delete_issue：从仓库中删除 issue

  • 必填：repo_slug、issue_id
  • 可选：workspace（默认为 kallows）

• bb_search_repositories：使用查询语法搜索 Bitbucket 仓库

  • 必填：query（例如，'name ~ "test"' 或 'project.key = "PROJ"'）
  • 可选：workspace（默认为 kallows）、page（默认为 1）、pagelen（默认为 10，最大为 100）

• bb_delete_file：从仓库中删除文件

  • 必填：repo_slug、path
  • 可选：workspace（默认为 kallows）、branch（默认为 main）、message（提交消息）

• bb_create_pull_request：创建拉取请求

  • 必填：repo_slug、title、source_branch
  • 可选：workspace（默认为 kallows）、destination_branch（默认为 main）、description、close_source_branch（默认为 true）

环境设置

服务需要通过环境变量设置 Bitbucket 凭据：

export BITBUCKET_USERNAME="your-username"
export BITBUCKET_APP_PASSWORD="your-app-password"

创建 Bitbucket 应用密码

1. 前往 Bitbucket Settings → App passwords
2. 创建具有以下权限的新应用密码：
   • 仓库：读取、写入、管理（用于删除操作）
   • 拉取请求：读取、写入
   • Issues：读取、写入
   • 账户：读取（用于工作区操作）

Claude Desktop 配置

将此配置添加到你的 claude_desktop_config.json：

Windows

{
  "mcpServers": {
    "bitbucket-api": {
      "command": "C:\\\\Users\\\\YOURUSERNAME\\\\.local\\\\bin\\\\uv.exe",
      "args": [
        "--directory",
        "D:\\\\mcp\\\\mcp-bitbucket",
        "run",
        "-m",
        "mcp_bitbucket.server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Mac 和 Linux

{
  "mcpServers": {
    "bitbucket-api": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/mcp-bitbucket",
        "-m", "mcp_bitbucket.server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

**⚠️ 重要：**修改配置文件后，必须重启 Claude Desktop。

使用方法

配置完成后，Bitbucket 工具将在 Claude Desktop 中可用。你可以：

• 让 Claude 创建仓库和分支
• 读取和写入仓库中的文件
• 创建和管理 issue
• 搜索仓库
• 创建拉取请求
• 管理仓库文件

示例查询：

• “在我的个人工作区中创建一个名为 'my-project' 的新仓库”
• “在 my-project 仓库中创建一个名为 'feature-xyz' 的新分支”
• “在 my-project 中创建一个包含一些基本内容的 README.md 文件”
• “搜索名称中包含 'python' 的仓库”

工作区配置

工具默认使用“kallows”工作区，但你可以：

• 使用 workspace 参数指定其他工作区
• 使用 workspace='~' 来操作你的个人工作区
• 如果你有相应权限，也可以在团队工作区中创建仓库

运行测试

该项目包含单元测试和集成测试：

# Run all tests
python -m unittest discover tests

# Run specific test files
python -m unittest tests.test_bb_api
python -m unittest tests.test_bb_integration

# Run with verbose output
python -m unittest discover tests -v

开发

添加新工具

1. 在 server.py 的 handle_list_tools() 中添加工具定义
2. 在 server.py 的 handle_call_tool() 中添加实现
3. 添加相应的测试
4. 更新此 README

错误处理

服务包含全面的错误处理：

• 权限错误及实用指导
• 网络连接问题
• 无效参数和验证
• Bitbucket API 速率限制

项目结构

mcp-bitbucket/
├── README.md
├── pyproject.toml
├── uv.lock
├── .gitignore
├── .python-version
├── src/
│   └── mcp_bitbucket/
│       ├── __init__.py
│       └── server.py
└── tests/
    ├── README.md
    ├── test_bb_api.py
    └── test_bb_integration.py

许可证

本项目采用 MIT 许可证。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 为你的更改添加测试
4. 确保所有测试均通过
5. 提交拉取请求

支持

如有问题或疑问：

• 查看 Bitbucket API 文档
• 确认你的应用密码权限
• 查看测试文件中的用法示例
• 在此仓库中创建问题