Bitbucket MCP

🚀 Bitbucket MCP Server (Python)

Claude Code、VS Code (GitHub Copilot)、Cursor、およびMCP互換のAIアシスタントをBitbucket Cloudリポジトリに接続します。自然言語でプルリクエストのレビュー、パイプラインの監視、コードの管理を行うことができます。

✨ 主な機能

• 45のMCPツール — リポジトリ、プルリクエスト、コメント、タスク、差分、パイプライン、ビルドステータス、レビュアー、ドラフトPR、一括レビューなど
• 軽量レスポンス — APIのノイズを取り除き、LLMのトークン使用量を削減
• 設定可能 — configs/tools.json または BITBUCKET_TOOLS_CONFIG 環境変数を使ってツールを有効/無効にできます
• 安全な資格情報管理 — 環境変数またはシステムのキーチェーンを使用

🚀 クイックスタート

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 — CLI（最速）：

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

📚 ドキュメント

利用可能なツール

デフォルトで無効になっているツール：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 パラメーターを受け入れ、差分を単一のファイルにフィルタリングできます。これにより、大規模なPRでのトークン使用量を約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 Registry — 公式MCPサーバーレジストリ
• PyPI Package — Pythonパッケージ
• MCP Python SDK
• Bitbucket API 2.0
• FastMCP Framework