MCP Bitbucket Python 🦊

MCP Bitbucket Python 🦊

Bitbucket 連携用の MCP サーバーを Python で実装しています。MCP（Model Context Protocol）により、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：リポジトリに課題を作成します

  • 必須：repo_slug、title、content
  • 任意：workspace（デフォルトは kallows）、kind（bug/enhancement/proposal/task）、priority（trivial/minor/major/critical/blocker）

• bb_delete_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. 次の権限を設定して、新しいアプリパスワードを作成します：
   • Repositories：Read、Write、Admin（削除操作用）
   • Pull requests：Read、Write
   • Issues：Read、Write
   • Account：Read（ワークスペース操作用）

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 にリポジトリやブランチの作成を依頼する
• リポジトリ内のファイルを読み書きする
• 課題を作成、管理する
• リポジトリを検索する
• プルリクエストを作成する
• リポジトリのファイルを管理する

クエリの例：

• 「個人のワークスペースに '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. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更内容のテストを追加します
4. すべてのテストが通ることを確認します
5. プルリクエストを送信します

サポート

問題や質問がある場合：

• Bitbucket API のドキュメントを確認します
• アプリパスワードの権限を確認します
• 使用例についてはテストファイルを確認します
• このリポジトリで Issue を作成します