Bitbucket MCP Server

Bitbucket MCP サーバー

Bitbucket 用の MCP サーバーです。リモートリポジトリをローカルクローンのように扱う必要がある AI コーディングエージェント向けに構築されています。grep のように高速なコード検索、ウィンドウ単位のファイル読み取り、トークン効率に優れたコンパクトな応答を提供し、Bitbucket のレート制限に抵触しないトランスポート層を備えています。

Bitbucket Server / Data Center（主な対象）と Bitbucket Cloud に対応しています。

v3 の変更点

	v2	v3
リポジトリ内のコンテンツ検索	1 回の一覧取得 + 最大 3,000 回のファイル GET	キャッシュなしなら 1 回のアーカイブ呼び出し、キャッシュありなら 0～1 回の呼び出し
検索の完全性	サーバーのスロットリング中に、通知なく結果が部分的になる	完全な結果を返し、すべての上限を報告
PR diff のトークン数	行ごとの JSON（約 4 倍のサイズ）	生の unified diff
100 行のウィンドウを読み取り	2 回の呼び出し、ファイル全体を転送	1 回の呼び出し、ウィンドウのみ
巨大なファイルのウィンドウを blame	最大 100 回の呼び出し	1 回の呼び出し
レート制限への安全性	なし（バーストにより → 429/403）	DC の制限に合わせたクライアント側の呼び出し間隔調整
ツール	33	25（定義コンテキストを約 30% 削減）

稼働中の Data Center インスタンスで測定した結果、コンテンツ検索を繰り返した場合、バーストスロットリングの影響で実際の 8 件中 1 件を見つけるのに 519 回の API 呼び出し / 約 7 秒かかっていたものが、8 件すべてを見つけるのに API 呼び出し 0 回 / 24 ミリ秒になりました。設計の全容と検証済みの API 調査については、REVAMP_PLAN.md をご覧ください。

ツール（25）

検索（search）— Server/DC のみ

• grep — ripgrep でローカルクローンを検索するように、すべてのブランチを対象に、完全な正規表現でファイルの内容を検索します。リポジトリとコミットの組み合わせごとに archive を 1 回ダウンロードし、一定のメモリ使用量でストリーミング処理します。プロセス内にキャッシュし、呼び出しのたびに鮮度を確認します（応答には as_of <commit> が含まれます）。query を省略すると、ファイル名のみを対象に glob で一覧表示します。モード：content、files、count。glob、path、context、case_insensitive、max_results に対応します。
• search_code — インデックスを利用して、プロジェクト全体を対象に完全一致する検索語を 1 回の呼び出しで検索します（デフォルトブランチのみ、大文字小文字を区別しない、正規表現なし、512 KiB 未満のファイル、約 1,000 件の結果ウィンドウ）。複数リポジトリをまたぐ識別子の検索に最適です。それ以外の検索には grep を使用してください。
• search_repositories — 名前または説明でリポジトリを検索します。

プルリクエスト（pr_core）

• get_pull_request — メタデータ、レビュアーのステータス、マージ情報を1 回の呼び出しで取得します。include_comments / include_file_changes（デフォルトは true）、include_tasks、comment_limit を指定できます。後続の変更操作に使用する version を返します。
• list_pull_requests — リポジトリ単位で取得します。repository（Server）を省略すると、role フィルターを使ってすべてのリポジトリにまたがる自分の PRを 1 回の呼び出しで取得できます。
• create_pull_request、update_pull_request、merge_pull_request、decline_pull_request — すべての変更操作で、以前の読み取りから取得した version を指定できます（取得処理を省略できます。409 競合時には自動で再取得し、1 回再試行します）。

コメントとタスク（pr_comments）

• add_comment — 通常のコメント、スレッドへの返信、インラインコメント（file_path + line_number、または code_snippet による自動解決）、コードの suggestion、またはタスク（Server では severity: "BLOCKER"）に対応します。添付ファイルは attachments パラメーターでアップロードできます（Server）。
• manage_comment — version を指定して、任意のコメントやタスクに対して edit / delete / resolve / reopen / to_task / to_comment を 1 回の呼び出しで実行します。

レビュー（pr_review）

• get_pull_request_diff — 生の unified diff テキストを取得します。file_path（サーバー側で適用）、include_patterns/exclude_patterns、context_lines、ignore_whitespace で範囲を指定できます。
• set_review_status — APPROVED / NEEDS_WORK / UNAPPROVED を設定します（相互排他的で、1 回の呼び出しで設定できます）。

コミット（commits）

• list_pr_commits、list_branch_commits（サーバー側の since-rev/merges フィルターに対応。クライアント側の author/until/search には上限付きのページ走査を使用）、get_commit_detail（unified diff。変更ファイル一覧のみの場合は detail: "files" を指定し、本文を省略できます）。

ブランチ（branches）

• list_branches、get_branch（ブランチとその PR）、delete_branch（expected_head を指定すると、検索呼び出しをスキップします）。

ファイル（files）

• get_file_content — サーバー側で範囲を指定：start_line／line_count を指定すると、その範囲（1 回あたり ≤5000 行）のみを転送します。ファイル全体または末尾を読み取るには、full_content／負の start_line を指定します。
• get_file_blame — 行範囲のコミット単位の blame を 1 回で取得します（Server）。
• list_directory_content — ページネーションに対応したコンパクトな出力です。

添付ファイル（attachments、Server）／検出（discovery）

• manage_attachments（download は上限あり、delete）、list_projects、list_repositories。

出力規約

• 大量のコンテンツ（差分、ファイル、grep の結果）は プレーンテキストで、JSON エスケープされた文字列ではありません。リストは整形せずコンパクトな JSON で出力します。日付は ISO-8601 形式です。
• コンテンツに基づくレスポンスには as_of <commit> が含まれるため、エージェントはどの時点の状態を確認したかを正確に把握できます。
• 切り捨てが黙って行われることはありません — 上限に達した場合は必ず、続きの取得方法（next_start、「glob を絞り込む」など）を明示する警告が返されます。
• 変更可能なエンティティには version が含まれるため、変更の前後で再読み込みする必要はありません。

インストール

Node.js 22 以降が必要です（18 と 20 はサポート終了しており、セキュリティ修正も提供されなくなっています）。

npx を使用する（推奨）

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@nexus2520/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_USERNAME": "your.username",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Bitbucket Cloud では、BITBUCKET_TOKEN の代わりに BITBUCKET_APP_PASSWORD を使用し、BITBUCKET_BASE_URL は省略してください。

認証情報の手順については、Cloud アプリパスワード · Server/DC HTTP トークンをご覧ください。

ソースからインストール

git clone https://github.com/pdogra1299/bitbucket-mcp-server.git
cd bitbucket-mcp-server
npm install && npm run build
# point your MCP config at: node <repo>/build/index.js

設定

数値ポリシーはすべて環境変数で調整でき、ハードコードされているものはありません。設定の全一覧は src/config/index.ts（CONFIG_REFERENCE）にあります。特に重要な項目は次のとおりです。

変数	デフォルト	用途
BITBUCKET_RATE_LIMIT_RPS	5	クライアント側の継続的なリクエストレート（DC のユーザーごとの補充レートは 5/s）。0 にするとペーシングが無効になります。アカウントに管理者によるレート制限の免除がある場合に設定してください
BITBUCKET_RATE_LIMIT_BURST	50	バースト容量（DC のサーバーバケットは 60）
BITBUCKET_GLOBAL_MAX_CONCURRENCY	8	すべてのツールを通じた同時実行リクエストの最大数
BITBUCKET_SNAPSHOT_MAX_MB	256	メモリ内 grep キャッシュの上限。0 = ストリーミングのみ（保持なし。検索あたり 2 回の呼び出しは引き続き必要）
BITBUCKET_SNAPSHOT_MAX_FILE_KB	2048	このサイズを超えるファイルはスキャンされますが、キャッシュされません
BITBUCKET_REF_RESOLVE_TTL_MS	15000	ブランチ→SHA の鮮度メモ。0 = 呼び出しのたびに検証
BITBUCKET_STREAM_ABORT_MB	2048	抽出した MB 数がこの値を超えるとアーカイブのスキャンを中止します（上限付きのファイル単位のスキャンに切り替わります）
BITBUCKET_HTTP_TIMEOUT_MS	30000	リクエストごとのタイムアウト
BITBUCKET_TOOL_GROUPS	all	公開するグループをカンマ区切りで指定します（検証済みで、ディスパッチ時に適用されます。検証に失敗した場合は拒否されます）
BITBUCKET_READ_ONLY	false	状態を変更するすべてのツール（PR の作成／更新／マージ／却下、コメント、レビュー状態、ブランチの削除、添付ファイルの削除）を非表示にし、実行も拒否します
BITBUCKET_DISABLED_TOOLS	—	グループ設定にかかわらず、非表示にして実行を拒否するツール名をカンマ区切りで指定します
BITBUCKET_PROTECTED_BRANCHES	—	delete_branch と merge_pull_request による操作を拒否するブランチ名／glob（main,release/*。ネストされたブランチには release/** を使用）
BITBUCKET_ATTACHMENT_ROOT	未設定 = アップロード無効	添付ファイルのアップロードで読み取りが許可される 唯一の ディレクトリ（実パスでの範囲制限あり。通常のファイルのみ）
BITBUCKET_ATTACHMENT_MAX_UPLOAD_MB / _DOWNLOAD_MB	25	添付ファイルのアップロード／ダウンロードのサイズ上限
BITBUCKET_GREP_TIMEOUT_MS	20000	コンテンツスキャンごとの実時間上限。超過した場合は PARTIAL と明記された結果を返します
BITBUCKET_GREP_MAX_SCAN_LINE_CHARS	16384	この長さを超える行はカウントして報告しますが、正規表現によるスキャンは行いません（圧縮されたファイルでの行ごとの正規表現処理コストを抑えます）

grep エンジンの保証

• メモリ使用量を制限：アーカイブはストリーミングされ、全体がバッファーに読み込まれることはありません。キャッシュは、LRU 方式の削除とブランチ間のコンテンツハッシュによる重複排除を行う、厳密なバイト数上限付きです。最悪の場合でも、上限に一時的な数 MB を加えた範囲に収まります。
• 最新の状態を維持：クエリごとにブランチの HEAD を再解決するため、ブランチが移動して古い結果が返されることはありません。このサーバーを通じて行われたマージや削除は、直ちにキャッシュを無効化します。
• 網羅性を確保：キャッシュの上限によってスキャン範囲が狭まることはありません。サイズ超過のファイルもスキャンされ、真のバイナリファイルのみがスキップされ、その件数は出力に含まれます。

レート制限

すべてのリクエストは、Bitbucket DC のユーザーごとのレート制限に合わせたトークンバケットを通過するため、429 が発生してから再試行するのではなく、発生自体を回避します。それでもインスタンスで厳しいスロットリングが発生する場合は、エラーメッセージに具体的な対処方法が示されます。恒久的な解決策は、Bitbucket 管理者にサービスアカウントのレート制限の適用除外（Admin → Rate limiting → Exemptions）を依頼し、BITBUCKET_RATE_LIMIT_RPS=0 を設定することです。

セキュリティ

このサーバーは、引数が LLM から渡されるツール呼び出しを実行します。多くの場合、そのトークンには書き込み権限があります。以下の制御が組み込まれています。

• 設定による最小権限。 BITBUCKET_READ_ONLY=true にすると、変更を伴うすべてのツールが tools/list とディスパッチの両方から除外されます。PR、差分、コードの読み取りだけが必要な自律型エージェントに推奨されます。BITBUCKET_DISABLED_TOOLS では個々のツールを無効化でき、BITBUCKET_PROTECTED_BRANCHES では指定したブランチ名やグロブに対する delete_branch / merge_pull_request をブロックできます。すべてのツールには MCP の readOnlyHint / destructiveHint アノテーションが付与されているため、クライアントはこれに基づいて確認を求めることができます。
• リクエストの誘導を防止。 workspace、repository、コミット ID、添付ファイル ID、ファイルパスは文字種を検証し、URL の各セグメントごとにパーセントエンコードします。そのため、PROJ/../../admin や repo?limit=1000 のような値によって、固定動詞を使用するツールの REST ルートが変わることはありません。
• 添付ファイルのアップロードはオプトイン方式で、サンドボックス化されています。 BITBUCKET_ATTACHMENT_ROOT が設定されていない場合、attachments パラメーターは拒否されます。設定されている場合は、実パス（シンボリックリンク解決後）がルート配下にあり、通常のファイルで、サイズ上限内である必要があります。すべての拒否で汎用メッセージを使用し、ツールがファイルシステム上の存在を判定できないようにします。ダウンロードにもサイズ上限が適用されます。
• 正規表現によるサービス拒否を防止。 呼び出し元の正規表現（grep の query、search_code の regex_filter）には文字数上限を設けています。グループ内に区切りのない可変幅の繰り返しがある状態で、グループに上限のない量指定子を適用する正規表現（(a+)+、(\w+\s*)*）は静的に拒否されます。さらに、vm のタイムアウトを設定して敵対的な入力で検証し、すべてのスキャンに実時間の期限（BITBUCKET_GREP_TIMEOUT_MS）を適用します。部分的な結果はその旨が示され、黙って返されることはありません。BITBUCKET_GREP_MAX_SCAN_LINE_CHARS より長い行はスキップされ、その件数が記録されます。追加の保護層として、起動時に V8 の線形時間正規表現フォールバックを有効にします。
• 認証情報の衛生管理。 トランスポートエラーはハンドラーに渡される前にステータス、メッセージ、レスポンスヘッダーへ正規化されます。エラーオブジェクト全体がログに記録されることはなく、ログ行から Authorization 形式の値が除去されます。Cloud のページネーションでは、設定済みのオリジンの next URL のみをたどります。
• 依存関係の最低要件。 Node ≥ 22。公開対象のツリーで npm run audit:prod が重大度「高」または「重大」のアドバイザリをゼロ件と報告する必要があります（CI で強制）。

自律型エージェント向けの推奨デプロイ構成：

"env": {
  "BITBUCKET_READ_ONLY": "true",
  "BITBUCKET_PROTECTED_BRANCHES": "main,release/*"
}

書き込み操作（コメント、承認、マージ）は、別の人間による確認を必要とするサーバーインスタンス、またはホスティングアプリケーション自体の承認フローを通じて実行してください。

v2 からの移行

削除されたツールと、v3 での同等機能（同じ機能をより少ないツールで提供）：

v2	v3
find_in_files	query を指定した grep
search_files	query を指定しない grep（glob を使用）
list_pr_tasks	get_pull_request + include_tasks: true
create_pr_task	add_comment + severity: "BLOCKER"
update_pr_task	manage_comment action: "edit"
delete_pr_task, delete_comment	manage_comment action: "delete"
set_pr_task_status	manage_comment action: "resolve" / "reopen"
convert_pr_item	manage_comment action: "to_task" / "to_comment"
set_pr_approval	set_review_status status: "APPROVED" / "UNAPPROVED"

Claude Code の権限許可リスト（mcp__bitbucket__*）もそれに合わせて更新してください。差分ツールは、行ごとの JSON ではなく統合差分テキストを返すようになりました。行番号は @@ ヘッダーから取得できます。詳細は CHANGELOG.md をご覧ください。

開発

npm run build   # tsc → build/
npm test        # build + node --test (unit + snapshot-engine tests)

アーキテクチャ：src/config（すべてのポリシー）・src/core（トランスポート、スナップショットエンジン、キャッシュ）・src/handlers（ツールのロジック）・src/tools（定義、ガード、レジストリ）・src/formatting（コンパクトな出力）・src/types（単一のバレル）。

ライセンス

MIT