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 框架