Bitbucket MCP Server

Bitbucket MCP Server（Python）

Claude Code、OpenAI Codex、Cursor、VS Code（GitHub Copilot）、およびMCP互換のあらゆるAIアシスタントをBitbucket Cloudリポジトリに接続できます。プルリクエストのレビュー、パイプラインの監視、コードの管理を、すべて自然言語で行えます。

機能

• 60以上のMCPツール — リポジトリ、プルリクエスト、コメント、タスク、差分、パイプライン（実行時＋設定）、ビルドステータス、レビュアー、下書きPR、一括レビュー、課題トラッカー、コミット、ソース／ファイルの閲覧
• MCP 2025ツールアノテーション — すべてのツールでreadOnlyHint／destructiveHint／idempotentHint／openWorldHintと人間が読みやすいタイトルを提示するため、クライアント（Claude Code、Cursor）は読み取り専用ツールを自動で含め、破壊的な操作の前に警告します
• スリムなレスポンス — APIの不要な情報を取り除き、LLMのトークン使用量を削減します
• 設定可能 — configs/tools.jsonまたはBITBUCKET_TOOLS_CONFIG環境変数でツールを有効／無効にできます
• 認証情報を安全に管理 — 環境変数またはシステムキーチェーンを使用します

クイックスタート

1. インストール

サーバーの実行には、uvxを使う方法を推奨します（インストール不要、隔離された環境）：

# Always latest version
uvx --from bitbucket-mcp-py bitbucket-mcp

# Pin a specific version
uvx --from bitbucket-mcp-py==1.8.1 bitbucket-mcp

--fromを使う理由 PyPIパッケージ名はbitbucket-mcp-pyですが、コマンドのエントリーポイントはbitbucket-mcpです。--fromフラグを使うと、インストールするパッケージをuvxに指定できます。

その他のインストール方法

モード	コマンド	おすすめの用途
pipグローバル	pip install bitbucket-mcp-py	シンプルで、インストールが保持されます
ローカル開発	プロジェクトディレクトリでpip install -e .	プロジェクトへの貢献
Docker	Dockerのセクションを参照	コンテナーを使うワークフロー

2. 認証情報を設定する

次の環境変数を設定します。上記のようにMCPクライアントのenvブロックに指定するか、システムキーチェーンに保存します（認証情報を参照）。

変数	説明
BITBUCKET_USERNAME	Bitbucketのメールアドレス
BITBUCKET_TOKEN	Bitbucket APIトークン
BITBUCKET_WORKSPACE	ワークスペースのスラッグ

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 [email protected] \
  -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": "[email protected]",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

OpenAI Codex

オプションA — CLI（最速）：

codex mcp add bitbucket-mcp \
  --env [email protected] \
  --env BITBUCKET_TOKEN=your-api-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

オプションB — TOML設定（~/.codex/config.toml）：

[mcp_servers.bitbucket-mcp]
command = "uvx"
args = ["--from", "bitbucket-mcp-py", "bitbucket-mcp"]
env = { BITBUCKET_USERNAME = "[email protected]", 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": "[email protected]",
        "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": "[email protected]",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

利用可能なツール

カテゴリ	ツール
リポジトリ	list_repositories, get_repository, get_repository_tags
プルリクエスト	get_pull_requests, get_pull_request, create_pull_request, update_pull_request, approve_pull_request, unapprove_pull_request, request_changes_pull_request, unrequest_changes_pull_request, decline_pull_request, merge_pull_request
コメント	get_pull_request_comments, add_pull_request_comment, get_pull_request_comment, update_pull_request_comment, delete_pull_request_comment, resolve_pull_request_comment, reopen_pull_request_comment, get_pull_request_activity
PR タスク	get_pull_request_tasks, get_pull_request_task, create_pull_request_task, update_pull_request_task, delete_pull_request_task
差分／レビュー	get_pull_request_diff, get_pull_request_patch, get_pull_request_diffstat, get_pull_request_commits
PR の検出	get_pull_requests_pending_review
ビルド／CI	get_pull_request_statuses, get_commit_statuses
パイプライン	list_pipeline_runs, get_pipeline_run, get_pipeline_steps, get_pipeline_step_logs, run_pipeline, stop_pipeline
パイプライン設定	get_pipeline_config, list_pipeline_variables, get_pipeline_variable, create_pipeline_variable, update_pipeline_variable, delete_pipeline_variable, list_pipeline_schedules, get_pipeline_schedule, list_pipeline_schedule_executions, create_pipeline_schedule, update_pipeline_schedule, delete_pipeline_schedule, list_pipeline_caches, delete_pipeline_cache
レビュアー	get_effective_default_reviewers, suggest_pull_request_reviewers
ドラフト PR	create_draft_pull_request, publish_draft_pull_request, convert_pull_request_to_draft
一括レビュー	submit_pull_request_batch_review
レビューの要約	get_pull_request_review_summary
課題	list_issues, get_issue, create_issue, update_issue, delete_issue, get_issue_comments, get_issue_comment, add_issue_comment, update_issue_comment, delete_issue_comment
コミット	list_commits, get_commit, get_commit_comments, get_commit_comment, add_commit_comment
ソース	get_file_content, list_directory
デプロイ	list_environments, get_environment, create_environment, delete_environment, list_deployments, get_deployment, list_deployment_variables, create_deployment_variable, update_deployment_variable, delete_deployment_variable
ブランチ制限	list_branch_restrictions, get_branch_restriction, create_branch_restriction, update_branch_restriction, delete_branch_restriction
ワークスペース	list_workspace_members, get_workspace_member, list_workspace_permissions, list_repository_permissions

デフォルトでは無効です：merge_pull_request（安全性）、stop_pipeline（安全性）、get_pull_request_patch（git am 形式のため、AI レビューには役立ちません）、convert_pull_request_to_draft（Bitbucket API ではサポートされていません）、delete_issue（安全性）、delete_issue_comment（安全性）、add_commit_comment（書き込み操作）、create_pipeline_variable／update_pipeline_variable／delete_pipeline_variable（書き込み操作）、create_pipeline_schedule／update_pipeline_schedule／delete_pipeline_schedule（書き込み操作）、delete_pipeline_cache（安全性）、create_environment／delete_environment／create_deployment_variable／update_deployment_variable／delete_deployment_variable（書き込み操作）、create_branch_restriction／update_branch_restriction／delete_branch_restriction（書き込み操作）。configs/tools.json で有効にしてください。 ガバナンスのスコープ — ブランチ制限の読み取りツールには repository スコープが必要です（リポジトリの設定によっては repository:admin が必要な場合があります）。書き込みツールには repository:admin が必要です。ワークスペースのメンバー／権限ツールには account スコープが必要です。/members エンドポイントはユーザーを一覧表示しますが、ユーザーごとの権限は返しません（ロールを確認するには list_workspace_permissions を使用してください）。

デプロイメントのスコープ — 読み取りツール（list_environments、get_environment、list_deployments、get_deployment、list_deployment_variables）には deployment スコープが必要です。書き込みツールには deployment:write が必要です。Bitbucket には環境でデプロイメントを絞り込むサーバー側のフィルターがありません（BCLOUD-18729）。代わりに、list_deployments の environment フィールドで絞り込んでください。update_environment ツールはありません。Bitbucket は環境に対する PUT を公開していません（ロック用の POST .../changes のみです）。

カスタムツールの設定

デフォルトでは、サーバーはパッケージに同梱されている 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")

トークンに関するヒント — get_pipeline_step_logs は、デフォルトでステップログの末尾 100 KiB のみを返します（長時間のステップでは、生ログが数 MB に達することがあります）。レスポンスには truncated フラグが含まれます。絶対バイト範囲 start／end で取得範囲を広げるか、max_bytes=null を渡すとログ全体を取得できます。ビルドコンテナーではなくサービスのログを読み取るには、サービスコンテナーの UUID を log_uuid として渡してください。このエンドポイントには実際のパイプライン UUID が必要です。ビルド番号しかない場合は、get_pipeline_run で UUID を取得してください。

get_pipeline_step_logs(repo_slug, pipeline_uuid="{adab6a1f-...}", step_uuid="{84fc6465-...}")

MCP プロンプト

サーバーは MCP プロンプト も公開します。これは、互換性のあるクライアント（Claude Code、Cursor など）でスラッシュコマンドとして表示される、パラメーター化されたテンプレートです。ツール名を覚える代わりに、プロンプトを実行すると、アシスタントが適切なツールを呼び出します。クライアントのプロンプト選択メニュー（prompts/list）に表示されます。

プロンプト	引数	内容
review_pull_request	repo_slug、pull_request_id	AI による包括的なレビュー：メタデータ → 差分統計 → 差分 → コメント → タスクの順に確認し、概要／リスク／品質／セキュリティ／推奨事項を提示します
debug_pipeline_failure	repo_slug、pipeline_uuid	失敗したパイプラインを診断：実行 → ステップ → 失敗したステップのログの順に確認し、根本原因／失敗したステップ／エラー／修正方法を提示します
summarize_repository	repo_slug	リポジトリの概要：情報 → 最近のコミット → オープン PR → CI → イシューの順に確認し、目的／活動状況／健全性／コントリビューターを提示します
onboard_reviewer	repo_slug、pull_request_id	新しいレビュアーを支援：PR のコンテキスト → コミット → 差分 → レビュー履歴の順に確認し、コンテキスト／変更点／これまでのレビュー状況／注目点を提示します

プロンプトの有効／無効は、configs/tools.json のトップレベルにある prompts キーで設定します（tools とは別です）。

認証情報

オプション 1：環境変数（推奨）

上記の例のように MCP クライアント設定の env ブロックに記述するか、サーバーを起動するシェルでエクスポートしてください。

オプション 2：システムのキーリング（最も安全）

pip install 'bitbucket-mcp-py[keyring]'
python3 -c "import keyring; keyring.set_password('bitbucket-mcp', 'bitbucket_token', 'YOUR_TOKEN')"

.env について：サーバー自体が .env ファイルを読み取ることはありません。.env.example はコンテナ用のテンプレートで、コンテナは --env-file .env または env_file:（Docker、Makefile、docker-compose.yml のセットアップ）を使用して読み込みます。uvx または python -m src.main を使用する場合は、オプション 1 または 2 を使用してください。

Docker（代替方法）

サーバーをコンテナで実行する場合：

docker build -t bitbucket-mcp-py .
docker run -d --name bitbucket-mcp --env-file .env bitbucket-mcp-py

次に、docker exec を使用するよう AI アシスタントを設定します：

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "bitbucket-mcp", "python", "-m", "src.main", "--transport", "stdio"]
    }
  }
}

トランスポート

サーバーはデフォルトで stdio（ローカル MCP クライアントの標準トランスポート）を使用します。ネットワークにデプロイする場合は、Streamable HTTP（MCP 仕様 2025-03-26）もサポートしています：

# Streamable HTTP on localhost:8080
python -m src.main --transport http --host 127.0.0.1 --port 8080

クライアントは http://<host>:<port>/mcp（例：http://localhost:8080/mcp）に接続します。

⚠️ --host のデフォルトはすべてのインターフェースを対象とする 0.0.0.0 です。--multi-tenant を指定しない場合、サーバー自体には認証機能がありません。ポートにアクセスできる人は誰でも、あなたの Bitbucket トークンを使用できます。認証プロキシの背後にポートがない限り、127.0.0.1 にバインドしてください。

--transport sse（レガシーの Server-Sent Events）も引き続き使用できますが、非推奨です。DeprecationWarning が出力されます。--transport http を使用してください。

ステートレス HTTP（水平スケーリング／サーバーレス）

--stateless を指定すると、サーバー側のセッションを使用せずに Streamable HTTP トランスポートが実行されます。Mcp-Session-Id は使われず、HTTP リクエストごとに新しいトランスポートが作成されます。ロードバランサーの背後にあるどのインスタンスでも、任意のリクエストを処理できます。スティッキーセッションは不要です。

python -m src.main --transport http --host 0.0.0.0 --port 8080 --stateless

⚠️ デフォルトはシングルテナントです。 --multi-tenant を指定しない場合、サーバーは呼び出し元すべてに、プロセス全体で使用する自身の Bitbucket トークンを提供します。プライベートネットワーク内または認証済みリバースプロキシの背後にデプロイするか、各呼び出し元がそれぞれの認証情報を持ち込むマルチテナントモードを使用してください。

--stateless を使用するには --transport http が必要です（stdio では拒否され、レガシーの sse ではアプリがこの設定を無視します）。また、SSE ストリームではなく 単一の JSON レスポンスを強制します。エッジ／サーバーレスのランタイムではストリーミングレスポンスを開いたままにできないためです。現時点では、ステートレスとストリーミングを組み合わせる方法はありません。

ロードバランサー向けに、両方の HTTP トランスポートで稼働状態エンドポイントを公開します：

curl http://localhost:8080/healthz    # {"status": "ok"}

コンテナ内の場合 — イメージのデフォルトの CMD は、exec ベースの stdio 使用向けにアイドル状態を保つため、サーバーモードを開始するにはコマンドを上書きします：

podman run -d --name bitbucket-mcp-http -p 127.0.0.1:8000:8000 --env-file .env bitbucket-mcp-py \
  python -m src.main --transport http --host 0.0.0.0 --port 8000 --stateless

コンテナ内では --host 0.0.0.0 が必要です。公開ポートをネットワークに公開しないようにするのは -p 127.0.0.1:8000:8000 です。このシングルテナントサーバーは、すべての呼び出し元に .env トークンを使用して応答するためです。

docker run でも同様に動作します。イメージはポート 8000 を公開します。

環境変数	デフォルト	用途
BITBUCKET_ALLOWED_HOSTS	(未設定)	カンマ区切りの Host 許可リスト。設定すると DNS リバインディング対策が有効になります。
BITBUCKET_ALLOWED_ORIGINS	(未設定)	カンマ区切りの Origin 許可リスト。
BITBUCKET_MAX_PAGES_HARD_CAP	10	ステートレスモードで、1 回のツール呼び出しが取得できる最大ページ数。これを超えると、レスポンスに truncated: true が含まれます。黙って切り捨てられることはありません。

2 つの許可リストは必ず同時に設定してください。空の Host 許可リストではすべてのリクエストが拒否され（421）、空の Origin 許可リストではすべてのブラウザクライアントが拒否されます（403）。片方だけを設定すると、サーバーへの接続をひそかに遮断するのではなく、起動時に拒否されます。

export BITBUCKET_ALLOWED_HOSTS="mcp.example.com"
export BITBUCKET_ALLOWED_ORIGINS="https://app.example.com"

どちらの許可リストも設定しない場合、DNS リバインディング対策は適用されません。プライベートネットワークまたは信頼できるプロキシ経由でアクセスするサーバーには適しています。実際のホスト名でサーバーを公開したら、すぐに設定してください。

マルチテナント HTTP（リクエストごとの認証情報）

デフォルトでは、HTTP デプロイメントはシングルテナントです。すべての呼び出し元が、プロセス全体で使用する Bitbucket トークンで操作します。--multi-tenant を指定すると、各リクエストに呼び出し元自身の Bitbucket OAuth アクセストークンを Authorization: Bearer として含め、そのユーザーの権限で実行します。サーバー自身は Bitbucket の認証情報を保持しません。

BITBUCKET_RESOURCE_SERVER_URL=https://mcp.example.com/mcp \
  python -m src.main --transport http --host 0.0.0.0 --port 8080 --stateless --multi-tenant

トークンは GET /2.0/user で検証され、呼び出し元の account_id とデフォルトのワークスペースが返されます。同じトークンは後続の API 呼び出しでも再利用されるため、認証情報が保存されたり、マッピングされたりすることはありません。認証されていないリクエストには、/.well-known/oauth-protected-resource/mcp を示す WWW-Authenticate チャレンジを含む 401 が返されます。Bitbucket は OAuth メタデータを公開していないため、サーバーは /.well-known/oauth-authorization-server を自ら提供し、Bitbucket のエンドポイントを示します。これにより、claude.ai にカスタムコネクターとして追加できます（Atlassian ログインを経由した Bitbucket サインイン）。設定手順、検証済みの内容、および残存リスクについては、docs/deployment-modes.md を参照してください。

これにより、次のメリットが得られます。

• 分離 — (identity, workspace) ごとに Bitbucket クライアントが 1 つ作成され、異なる呼び出し元が同じクライアントを共有することはありません。また、フォールバック先となるプロセストークンもありません。
• workspace=None は あなたの ワークスペースを意味します — BITBUCKET_WORKSPACE ではなく、呼び出し元のメンバーシップから解決されます。メンバーシップが 0 件または複数ある場合、デフォルトは設定されず、呼び出し時にワークスペースを指定する必要があります。
• 監査証跡 — すべての呼び出しは、ツール、account_id、ワークスペースとともに bitbucket_mcp.audit ロガーに記録されます。認証情報は記録されません。
• より厳格なデフォルト設定 — destructiveHint が設定されたツールは、明示的に有効化しない限り拒否されます。その他の書き込みツール（コメント、承認、プルリクエストの作成、パイプラインの実行など）はすべての呼び出し元が引き続き利用できます。初回デプロイでは BITBUCKET_MULTITENANT_READ_ONLY=1 を設定してください。

環境変数	デフォルト	用途
BITBUCKET_RESOURCE_SERVER_URL	(必須)	MCP エンドポイントの公開 URL（例：https://mcp.example.com/mcp）。OAuth リソース識別子です
BITBUCKET_OAUTH_ISSUER_URL	(このサーバーのオリジン)	アドバタイズする認可サーバーです。未設定のままにすると、サーバーが OAuth メタデータを自ら公開します
BITBUCKET_CLIENT_CACHE_SIZE / _TTL	128 / 900	ID ごとのクライアントキャッシュの上限（LRU ＋ TTL、秒）。TTL を 0 にすると、リクエストごとに新しいクライアントが作成されます
BITBUCKET_TOKEN_CACHE_SIZE / _TTL	256 / 300	キャッシュするトークン検証結果の上限です。TTL は失効反映までの時間です。すべてのリクエストを検証するには 0 に設定してください
BITBUCKET_MULTITENANT_ALLOW_DESTRUCTIVE	(オフ)	configs/tools.json で有効になっている破壊的なツールを許可します。デフォルトでは decline_pull_request、delete_pull_request_comment、delete_pull_request_task が対象です。merge、stop_pipeline、delete_issue* は引き続き無効です
BITBUCKET_MULTITENANT_READ_ONLY	(オフ)	読み取り専用ツールのみを公開します
BITBUCKET_MULTITENANT_ALLOWED_WORKSPACES	(未設定：すべてのアカウント)	ワークスペースのスラッグをカンマ区切りで指定します。指定したワークスペースのメンバーのみが許可され、他のワークスペースにはアクセスできません。公開エンドポイントでは必ず設定してください

仕様からの逸脱：呼び出し元の Bitbucket トークンはオーディエンスチェックなしで受け入れられ、そのまま上流に転送されます。これは MCP 認可仕様（2025-11-25）で禁止されています。トレードオフと残存リスクについては、docs/deployment-modes.md を参照してください。

このモードではサポートされません：Bitbucket Repository/Workspace Access Token はユーザーアカウントに紐付いていないため、ID を特定できません。この場合はシングルテナント HTTP を使用してください。Bearer トークンには TLS が必要です。サーバーの前段で HTTPS を終端してください。

stdio には影響しません — 上記の説明どおり、環境変数を使用するシングルユーザーモードのままです。

3 つのデプロイモードの全体比較と各モードの脅威モデルについては、docs/deployment-modes.md を参照してください。

Kubernetes（k3s、データセンター、GKE）

各リリースでは、マルチテナント HTTP モードをデプロイするマルチアーキテクチャイメージ（ghcr.io/lawp09/bitbucket-mcp）と Helm チャート（oci://ghcr.io/lawp09/charts/bitbucket-mcp）が公開されます。必須の値は publicUrl のみです。

helm upgrade --install bitbucket-mcp oci://ghcr.io/lawp09/charts/bitbucket-mcp --version <version> \
  -n bitbucket-mcp --create-namespace --set publicUrl=https://mcp.example.com

Ingress、GKE、ネットワークポリシーに関する注意事項については、docs/deployment-kubernetes.md を参照してください。

開発

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run specific test
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