Bitbucket MCP

bitbucket-cli

ライブの OpenAPI 仕様を基に構築された、メンテナンス負荷の低い Bitbucket Cloud ツールです。ソフトウェアエンジニア向けの CLI、AI エージェント向けの MCP サーバー、DevSecOps チーム向けの Terraform プロバイダーを提供します。

重要

https://github.com/FabianSchurig/bitbucket-cli が正式なリポジトリです。 このプロジェクトを terraform-provider-bitbucket ミラー経由で見つけた場合は、bitbucket-cli でウォッチ、スター、課題の報告、コントリビュートを行ってください。

まずはこちら

対象ユーザー	最適なツール	まずはこちら
DevSecOps エンジニア	Terraform プロバイダー	Terraform Registry、生成されたプロバイダードキュメント、例：bitbucket_tags
ソフトウェアエンジニア／コンピューターサイエンティスト	bb-cli	CLI の使用ガイド
AI エージェント／エージェントプラットフォームのユーザー	bb-mcp	MCP の使用ガイド

クイックリンク

• 正式な GitHub リポジトリ
• Terraform Registry：FabianSchurig/bitbucket
• ミラーリポジトリ：terraform-provider-bitbucket
• GitHub リリース
• SonarQube Cloud
• コントリビューションガイド

インストール

Homebrew（macOS と Linux）

カスタム tap 経由で CLI ツールをインストールするには、リポジトリを tap に追加し、サプライチェーンのリスクを軽減するために数式を明示的に信頼してください。

brew tap FabianSchurig/tap
brew trust --formula FabianSchurig/tap/bitbucket-cli
brew install bitbucket-cli

または、MCP サーバーをインストールするには、次のコマンドを実行します。

brew tap FabianSchurig/tap
brew trust --formula FabianSchurig/tap/bitbucket-mcp
brew install bitbucket-mcp

（注：以前に古い cask を tap に追加していた場合は、コマンドを実行する前に brew untap fabianschurig/tap で安全に tap を解除できます。）

APT（Debian／Ubuntu）

最新リリースから .deb パッケージをダウンロードしてインストールしてください。対応アーキテクチャ：amd64、arm64。

TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(dpkg --print-architecture)
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.deb"
sudo dpkg -i "bb-cli_${VERSION}_${ARCH}.deb"

代わりに MCP サーバーをインストールするには、bb-cli を bb-mcp に置き換えてください。

RPM（Fedora／RHEL／CentOS）

最新リリースから .rpm パッケージをダウンロードしてインストールしてください。対応アーキテクチャ：amd64、arm64。

TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.rpm"
sudo rpm -i "bb-cli_${VERSION}_${ARCH}.rpm"

代わりに MCP サーバーをインストールするには、bb-cli を bb-mcp に置き換えてください。

Scoop（Windows）

scoop bucket add bitbucket https://github.com/FabianSchurig/scoop-bucket
scoop install bb-cli
scoop install bb-mcp

Winget（Windows）

winget install FabianSchurig.bb-cli
winget install FabianSchurig.bb-mcp

インストールスクリプト

curl -fsSL https://raw.githubusercontent.com/FabianSchurig/bitbucket-cli/main/install.sh | sh

バージョンの選択、バイナリの選択（bb-cli、bb-mcp、または all）、カスタムのインストールディレクトリについては、install.sh のオプションを参照してください。

その他の方法

方法	コマンド
Go でインストール	go install github.com/FabianSchurig/bitbucket-cli/cmd/bb-cli@latest
Docker	docker pull ghcr.io/fabianschurig/bitbucket-cli:latest
バイナリをダウンロード	GitHub Releases

インストールの詳細については、CLI の使用ガイドと MCP の使用ガイドを参照してください。

このプロジェクトについて

このリポジトリでは、Bitbucket の OpenAPI 仕様から大部分を生成することで、Bitbucket Cloud のツール群を保守しやすくしています。

• 1 つの API 記述から、ユーザー向けツールを 3 つ生成：CLI、MCP、Terraform はすべて同じスキーマパイプラインから生成されます。
• 手書きのランタイムは最小限：認証、ディスパッチ、出力、Terraform のランタイムは汎用的なまま保たれ、エンドポイントごとの接着コードが増えないようにしています。
• 仕様への迅速な対応：新しい Bitbucket エンドポイントは、大規模な手動書き換えではなく、生成によって追加されます。
• 保守性を優先した設計：開発作業の中心は、エンドポイントごとに重複したコードではなく、共有ジェネレーターとランタイムです。
• 内部／非公開のエンドポイントも同じ方法でサポート：Bitbucket の公開 OpenAPI 仕様に含まれないエンドポイント（たとえば、https://bitbucket.org/!api/internal/... 経由でのみ公開されるプロジェクトレベルのブランチ制限エンドポイント）用に、schema/ 以下のスキーマを手書きできます。ジェネレーターとランタイムはこれらを同じように扱います。スキーマのパスには絶対 URL を指定でき、ディスパッチャーは変更せずにそのまま渡します。

アーキテクチャ

flowchart LR
    A[Live Bitbucket OpenAPI spec] --> B[enrich_spec.py]
    B --> C[partition_spec.py]
    C --> D[schema/*-schema.yaml]
    D --> E[oapi-codegen models]
    D --> F[CLI generator]
    D --> G[MCP generator]
    D --> H[Terraform generator]
    E --> I[Shared generated types]
    F --> J[bb-cli]
    G --> K[bb-mcp]
    H --> L[terraform-provider-bitbucket]
    I --> J
    I --> K
    I --> L
    M[Hand-written runtime\nauth, dispatch, output, MCP handler, TF runtime] --> J
    M --> K
    M --> L

実際には、次のように動作します。

• CLI は Bitbucket の操作をターミナルコマンドとして公開します。
• MCP は同じ操作を AI エージェント向けのツール呼び出しとして公開します。
• Terraform は操作グループを汎用リソースとデータソースに対応付けます。
• 手書きコードは意図的に最小限に抑えています。エンドポイントの網羅は生成コードが担います。

CI パイプライン

flowchart TD
    A[push / pull_request] --> B[ci.yml]
    A --> C[terraform-tests.yml]
    D[schedule / manual] --> E[schema-sync.yml]
    E --> F[Fetch live spec]
    F --> G[Regenerate code and docs]
    G --> H[Build and test]
    H --> I[Tag new version]
    I --> J[release.yml]
    J --> K[docker.yml]
    I --> L[terraform-release.yml]
    K --> M[Publish to MCP Registry]

• ci.yml：ビルド、リンティング、静的解析、Go テストを実行し、SonarQube Cloud に解析結果を送信します。
• terraform-tests.yml：モックベースの Terraform 受け入れテストと terraform test スイートを実行し、認証情報がある場合は実 API テストも実行します。実 API テストで現在検証しているエンドポイントの一覧は、docs/e2e-coverage.mdを参照してください。
• schema-sync.yml：毎日または手動で同期を実行し、最新の Bitbucket 仕様を取得して生成アーティファクトを再生成し、ドキュメントを再構築してすべてをテストします。スキーマに変更があった場合はリリースにタグを付けます。
• release.yml：GoReleaser を使用して、タグ付きバイナリリリースを公開します。
• docker.yml：bb-cli と bb-mcp のマルチアーキテクチャコンテナイメージをビルドして GHCR にプッシュし、SBOM と CVE レポートを公開（サプライチェーン：SBOM と CVE レポートを参照）するとともに、MCP Registry に bb-mcp サーバーを公開します。
• terraform-release.yml：タグ付きソースを terraform-provider-bitbucket にミラーし、Terraform プロバイダーのリリースを公開します。

スキーマ同期の安全性

ライブの OpenAPI ドキュメントは入力として扱われ、一時的な欠落を理由に稼働中の API グループを削除する権威ある情報源とは見なされません。次の 3 つの仕組みにより、日次同期で公開済みのインターフェースや同期処理自体が壊れるのを防ぎます。

• グループの保持：グループからパスが抽出されなかった場合、partition_spec.py は既存の内容があるスキーマを保持します。実際に空のグループや新しいグループは、引き続き通常どおり書き込まれます。
• 安定した operationId：ID は、"<method> <path>" をキーとして、コミット済みのロックファイル schema/operation-ids.json に記録されます。操作の ID は永久に維持され、削除された操作の ID も予約されたままになります。そのため、兄弟エンドポイントが ID を引き継ぎ、リリース済みの CLI コマンド、MCP ツール、または CRUDConfig の参照名を気付かれないまま変更することはありません。
• 操作の保持：Atlassian は、非推奨ではあるもののまだ機能するエンドポイントを公開仕様から定期的に削除します。自動パッチリリースでコマンドを削除するのではなく、partition_spec.py はコミット済みスキーマから該当する操作をそのまま引き継ぎ、x-bb-cli-retained: true の注釈を付けます。これにより、スキーマ差分で上流が公開を停止した内容を正確に確認できます。操作を完全に廃止するには、意図的に schema/*-schema.yaml から削除します。すると不変条件テストによって、引き続き参照している手動管理のマッピング（たとえば CRUDConfig 内のもの）があれば検出されます。

internal/tfprovider/acceptance_test.go の受け入れテストは手書きであり、スキーマ生成によって削除されることはありません。生成される Terraform のフィクスチャは、残存するリソースグループから再生成されます。また、変更のコミットまたはリリース前に、モック Terraform 受け入れテストスイートを含むスキーマ同期のビルドおよびテストゲートに合格する必要があります。生成された実際の API カバレッジレポートにより、手作業で記録しなくても、カバレッジのないグループを確認できます。

サプライチェーン：SBOM と CVE レポート

リリースされるすべてのコンテナーイメージには、標準形式のソフトウェア部品表と脆弱性レポートが付属します。どちらも、GHCR にプッシュされた正確なイメージダイジェストを基に生成されます。

成果物	形式	入手先
イメージ SBOM	SPDX 2.3 JSON	対応するGitHub Releaseの sbom-bitbucket-cli.spdx.json / sbom-bitbucket-mcp.spdx.json、またはイメージ自体に付与された署名付きアテステーション
イメージ CVE レポート	Grype JSON + プレーンテキストの表	対応する GitHub Release の cves-bitbucket-cli.{json,txt} / cves-bitbucket-mcp.{json,txt}
ソース SBOM	SPDX JSON	release.yml によって GitHub Release に添付（イメージではなく Git タグを対象）

SBOM は署名付きのダイジェストに紐付けられた GitHub アテステーションとしてイメージにも添付されているため、利用者はこのリポジトリにアクセスしなくても検証して取得できます。

gh attestation verify oci://ghcr.io/fabianschurig/bitbucket-mcp:latest --owner FabianSchurig
gh attestation download oci://ghcr.io/fabianschurig/bitbucket-mcp:latest --owner FabianSchurig

ランタイムイメージは FROM scratch からビルドされ、静的バイナリと CA 証明書のみを含むため、SBOM は意図的に小さく、パッチ適用が必要な OS パッケージもありません。

脆弱性スキャンの結果は、メンテナー向けに GitHub code scanning（カテゴリ docker-bitbucket-cli および docker-bitbucket-mcp）にもアップロードされます。また、Go モジュールツリーは security.yml で govulncheck によってチェックされます。

DrFaust92/terraform-provider-bitbucketとの違い

項目	DrFaust92/terraform-provider-bitbucket	FabianSchurig/bitbucket
メンテナンスモデル	手書きのプロバイダーリソース	主に稼働中のBitbucket OpenAPI仕様から生成
対象範囲	Terraformプロバイダーのみ	Terraformプロバイダー＋CLI＋MCPサーバーを1つの正式なリポジトリで提供
APIカバレッジのモデル	厳選された型付きリソース	グループ化された汎用リソース／データソースによる幅広いエンドポイントのカバレッジ
更新フロー	リソースごとに手動で機能を追加	スキーマ同期パイプラインでコードとドキュメントを再生成
リソースの構造	リソース固有の型付きフィールド	汎用パラメーター、レスポンスフィールド、生のAPIレスポンス
最適な用途	独自の方針に基づくTerraformワークフロー	Terraform、シェル、AIエージェントで共有するツールを通じて、Bitbucket APIを迅速にカバーしたいチーム

このプロジェクトは、幅広いカバレッジ、メンテナンス性、インターフェース間で共有できるインフラストラクチャを重視しています。手厚くモデル化されたTerraform UXをお求めの場合は、DrFaust92のプロバイダーのほうが使い慣れているかもしれません。Terraform、CLI、MCPをBitbucket Cloudに合わせて維持する単一のパイプラインをお求めの場合は、このリポジトリがそのために設計されています。

ドキュメント一覧

まずこのページの簡単なガイドを使って始め、その後、必要なインターフェースの詳細ドキュメントをご覧ください。

• CLI：docs/cli.md
• MCP：docs/mcp.md
• Terraformプロバイダーのドキュメント：docs/index.mdおよびTerraform Registryのドキュメント
• 実際のAPIを使ったE2Eテストのカバレッジ：docs/e2e-coverage.md — TestAccRealAPI_*テストで検証されているリソースグループと、まだカバレッジがないリソースグループを一覧にした自動生成ドキュメントです。

docs/以下のTerraformドキュメントは生成されています。ルートのREADMEでは、概要、リンク、アーキテクチャ、メンテナンス、コントリビューションの入り口に焦点を当てています。

メンテナンスとコントリビューション

• ジェネレーターや実行時コードを変更する前に、CONTRIBUTING.mdをお読みください。
• 生成ファイルを直接編集しないでください。代わりにジェネレーターまたはスキーマソースを修正してください。
• すべてのエンドポイントにわたる共有パイプラインや手書きの実行時コードを改善する変更を優先してください。
• 正式なbitbucket-cliリポジトリで、イシューやプルリクエストを作成してください。