Bitbucket MCP Server

本番運用に重点を置いた Model Context Protocol サーバーで、Bitbucket Cloud および Bitbucket Server/Data Center からプルリクエストのメタデータと差分を取得し、オプトインでプルリクエストコメントにも対応します。

機能

• Bitbucket Cloud とセルフホスト型 Bitbucket Server/Data Center をサポートします。

• プルリクエストのメタデータ、差分、レビュー議論、一般/インラインコメントに特化したツールを公開します。

• Bearer トークンと基本認証をサポートします。

• Bitbucket が提供する場合、生の差分と構造化された変更ファイルデータの両方を返します。

• 設定可能な glob パターンにより、生成されたファイル、フォルダー、またはファイルタイプを除外します。

• UTF-8 文字を壊すことなく大きな差分に上限を設けます。

• プロトコルを壊すログを stdout に書き出さず、stdio を使用します。

• コメント作成はデフォルトで無効のままとし、プルリクエストの承認、マージ、その他の変更は行いません。

Related MCP server: Atlassian Bitbucket MCP Server

クイックスタート

対応する Node.js LTS リリース（Node.js 22 以降）が必要です。

git clone https://github.com/inceon/bitbucket-mcp.git
cd bitbucket-mcp
npm install
npm run build
cp .env.example .env

BITBUCKET_URL と BITBUCKET_TOKEN を MCP クライアント設定に設定し、コンパイル済みサーバーを node dist/index.js で起動してください。このサーバーは意図的に .env ファイルを自分で読み込みません。MCP クライアントが環境変数を直接渡す必要があります。

認証

Bearer 認証がデフォルトであり、Bitbucket Server/Data Center の個人アクセストークンに推奨されます:

BITBUCKET_URL=https://bitbucket.example.com/bitbucket
BITBUCKET_TOKEN=your-personal-access-token
BITBUCKET_AUTH_TYPE=bearer

基本認証が必要な Bitbucket Cloud API トークンまたはアプリパスワードの場合:

BITBUCKET_URL=https://api.bitbucket.org
BITBUCKET_TOKEN=your-api-token-or-app-password
BITBUCKET_AUTH_TYPE=basic
BITBUCKET_USERNAME=your-bitbucket-username

有効にするツールに必要な権限のみを認証情報に付与してください。コメント作成には、プルリクエストコメントを作成する権限が必要です。認証情報をコミットしたり、実際のトークンを issue レポートに記載したりしないでください。

環境変数

サーバーは起動時エラーを stderr にのみ書き出し、Bitbucket HTTP エラースニペットから設定された認証情報をマスクします。

MCP 設定

Claude Desktop の設定:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org",
        "BITBUCKET_TOKEN": "your-token"
      }
    }
  }
}

Codex の config.toml 設定:

[mcp_servers.bitbucket]
command = "node"
args = ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"]

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://api.bitbucket.org"
BITBUCKET_TOKEN = "your-token"

利用可能なツール

get_pull_request

プルリクエストのメタデータ（説明、状態、作成者、レビュアー、ブランチ、タイムスタンプ、リンク）を返します。

{
  "name": "get_pull_request",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123
  }
}

get_pull_request_comments

既存の一般コメントとインラインコメントを、プロバイダー独自のコメントオブジェクトとして返します。レビュー指摘を投稿する前に、既存のフィードバックを考慮するために使用してください。設定された取得上限に達すると、commentsStatus.complete は false になり、理由は max_comments または max_pages になります。

get_pull_request_commits

現在プルリクエストにあるプロバイダー独自のコミットを返します。指摘の発端となったコミットを追跡したり、後続の作業で対処されているかを確認したりするために使用します。設定された取得上限に達すると、commitsStatus.complete は false になり、理由は max_commits または max_pages になります。

get_pull_request_diff

利用可能な場合、git スタイルのレビュー差分と構造化された変更ファイルを返します。

{
  "name": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJECT_KEY",
    "repository": "my-repository",
    "pull_request_id": 123,
    "ignore_patterns": ["dist/**", "**/*.generated.ts", "package-lock.json"],
    "path": "src/service.ts",
    "context": 5,
    "ignore_whitespace": true,
    "renames": true
  }
}

差分出力は、後方互換性のある JSON テキストと MCP の structuredContent の両方として利用でき、公開された出力スキーマを備えています。含まれるもの:

• provider、pull_request_id、rawDiff、rawDiffBytes、rawDiffSource。rawDiffSource は、Cloud では provider_raw、ローカルで正規化された Server/Data Center 応答では server_structured になります。

• truncated と truncationReason: 上流の Cloud 読み取り上限に達した場合は input_limit、フィルタリング後の結果が BITBUCKET_MAX_DIFF_BYTES を超えた場合は output_limit、Server/Data Center が構造化差分を切り詰め済みとマークした場合は provider_limit です。

• オプションのコンパクトな files エントリには、path、正規化された status、およびリネームまたはコピーの場合の oldPath のみが含まれます。必須の filesStatus は完全性を報告します。complete が false の場合、理由は max_files、max_pages、または unsupported で、returned は実際に返されたフィルタリング済みエントリを反映します。

• 除外が有効な場合のオプションの ignored メタデータ。

完全な結果:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 128,
  "rawDiffSource": "provider_raw",
  "files": [],
  "filesStatus": { "available": true, "complete": true, "returned": 0 },
  "truncated": false
}

上限付きの部分結果:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 200000,
  "rawDiffSource": "provider_raw",
  "files": [{ "path": "src/service.ts", "status": "modified" }],
  "filesStatus": {
    "available": true,
    "complete": false,
    "returned": 1,
    "reason": "max_pages"
  },
  "truncated": true,
  "truncationReason": "output_limit"
}

切り詰められた rawDiff は UTF-8 セーフなレビュー用プレフィックスであり、必ずしも完全な行、ハンク、または適用可能なパッチではありません。

構造化ファイルページは、完了するか、設定されたファイル数/ページ数の上限に達するまで追跡され、その後、プロバイダーのハッシュ、リンク、重複するパス構造を返すのではなく、コンパクトなレビューメタデータに正規化されます。利用できない diffstat または changes エンドポイントは、HTTP 404 の後にのみ報告されます。認可、レート制限、サーバー、不正な応答、タイムアウト、転送の失敗は、メタデータを黙って省略するのではなく、ツール呼び出しを失敗させます。

Cloud の rawDiff はプロバイダーの生の応答を保持します。Server/Data Center は構造化された /diff 応答を使用し、そのファイル、ハンク、セグメント、行を git スタイルのレビューテキストに正規化します。これにより、別の .diff エクスポート経路でのバージョン固有の失敗を回避できます。rawDiffSource はその違いを明示します。

path は両プロバイダーでサポートされており、大きなプルリクエストをファイル単位でレビューする推奨方法です。返される files メタデータは同じパスにスコープされます。renames は Cloud のみです。context は Cloud の context と Server/Data Center の contextLines に対応します。ignore_whitespace は Cloud の ignore_whitespace と Server/Data Center の whitespace=ignore-all に対応します。これらが指定されていない場合、プロバイダーのデフォルトは変更されません。

パターンはリポジトリ相対パスを使用し、*、**、? をサポートします。package-lock.json や *.png のように / を含まないパターンは、そのファイル名を任意の場所で照合します。末尾のスラッシュはディレクトリを再帰的に除外します。除外が有効な場合、応答には ignored.patterns、ignored.files、ignored.rawDiffFiltered が含まれます。rawDiffFiltered が false の場合、Cloud プロバイダーが安全にフィルタリングできない非 git 差分形式を返したことを意味します。コンテンツを黙って落とす代わりに、応答が保持されます。

add_pull_request_comment

プルリクエストに一般コメント、ファイルレベルコメント、またはインライン行コメントを作成します。この書き込み操作は、MCP サーバー環境で BITBUCKET_ENABLE_WRITE_TOOLS=true が設定されている場合にのみ利用できます。

一般コメント:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "The implementation looks good. Please add a regression test for the empty input case."
  }
}

追加された行へのインラインコメント:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "Please handle an empty value here.",
    "file_path": "src/service.ts",
    "line": 42,
    "line_type": "added"
  }
}

line_type には added、removed、context のいずれかを使用します。追加行はデフォルトで new 側、削除行はデフォルトで old 側、コンテキスト行はデフォルトで new になります。コンテキストコメントを old に配置するには、line_side を明示的に設定してください。ファイルレベルコメントには、行フィールドなしで file_path を指定します。Server/Data Center でリネームされたファイルの場合、source_file_path で以前のパスを指定できます。

認証された Bitbucket ユーザーがコメント作成者になります。MCP クライアントでツール呼び出しを承認する前に、対象のワークスペース、リポジトリ、プルリクエスト ID、コメントテキストを確認してください。

プロバイダーの動作

URL のホストがプロバイダーを決定します。bitbucket.org と api.bitbucket.org は Bitbucket Cloud を使用し、その他のすべてのホストは Server/Data Center を使用します。

Cloud URL は 1 つの /2.0 API プレフィックスに正規化され、以下を使用します:

• /repositories/{workspace}/{repository}/pullrequests/{id}

• /repositories/{workspace}/{repository}/pullrequests/{id}/diff

• /repositories/{workspace}/{repository}/pullrequests/{id}/diffstat

• /repositories/{workspace}/{repository}/pullrequests/{id}/comments (GET; 有効時は POST)

• /repositories/{workspace}/{repository}/pullrequests/{id}/commits (GET)

Server/Data Center URL は /bitbucket などのコンテキストパスを保持し、1 つの /rest/api/1.0 プレフィックスに正規化して、以下を使用します:

• /projects/{project}/repos/{repository}/pull-requests/{id}

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff（git スタイルのレビューテキストに正規化された構造化差分）

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff/{path}（パスにスコープされた構造化差分）

• /projects/{project}/repos/{repository}/pull-requests/{id}/changes

• /projects/{project}/repos/{repository}/pull-requests/{id}/comments (GET; 有効時は POST)

• /projects/{project}/repos/{repository}/pull-requests/{id}/commits (GET)

オプションの diffstat または changes リクエストは、HTTP 404 の後に filesStatus.reason: "unsupported" を報告します。その他の HTTP、タイムアウト、転送、解析の失敗はツール呼び出しを失敗させ、不完全なメタデータが完全な応答と誤認されることを防ぎます。

Atlassian Rovo MCP

Atlassian は Cloud 専用の bitbucketPullRequest.diff アクションを文書化していますが、その引数スキーマ、出力形式、ページネーション、フィルタリング、切り詰め契約は公開していません。したがって、このサーバーは直接の Bitbucket API を正規の情報源として維持します。Rovo アダプターは、実際の tools/list スキーマと制御された diff レスポンスを検証した後にのみ追加すべきであり、明示的に設定された状態を維持する必要があり、Server/Data Center サポートを置き換えることはできません。Atlassian のサポート対象ツールページ を参照してください。

ロードマップ

今後のリリースで計画されている領域は次のとおりです。

• リトライ処理と、より明確なレート制限診断を追加する。

• プロバイダー固有のフィールドへのアクセスを維持しつつ、正規化されたプルリクエスト出力を提供する。

• プルリクエストの一覧表示とビルドステータス取得のための読み取り専用ツールを追加する。

• stdio をデフォルトに保ちながら、オプションの Streamable HTTP トランスポートを提供する。

• より簡単なインストールおよびアップグレードパスでバージョン付きリリースを公開する。

書き込み操作はデフォルトで無効のままです。承認、マージ、その他の影響の大きい Bitbucket 操作は計画されていません。アイデアや実装提案は GitHub issues を通じて歓迎します。

開発

npm run dev        # Run directly from TypeScript
npm run build      # Compile to dist/
npm test           # Run the test suite once
npm run test:watch # Run tests in watch mode
npm run check      # Build and test, matching CI

コマンドレジストリは、各 MCP ツールを src/tools の下に分離して保持します。プルリクエストを開く前に CONTRIBUTING.md を参照してください。

セキュリティ

このサーバーは認証情報をメモリ内で処理し、設定された BITBUCKET_URL にのみ送信します。サーバーを起動する前に、その URL を慎重に確認してください。書き込みツールを有効にすると、接続された MCP クライアントが認証済みの Bitbucket ユーザーとして PR コメントを投稿できるようになります。脆弱性を非公開で報告するには、SECURITY.md に従ってください。

ライセンス

MIT License の下で公開されています。