bitbucket-mcp

Bitbucket Cloud 用 MCP サーバー。 プルリクエスト、コードレビュー、ブランチ、ソース、 パイプライン、Webhook、変数を、生の REST 呼び出しではなく制御されたツールサーフェスとして 公開します。

存在理由

公式の Atlassian MCP は Jira と Confluence のみを対象としています。Bitbucket は対象外のため、 リポジトリ操作はすべて手書きの REST 呼び出しに頼ることになります。冗長なペイロード、ガードレールなし、 そしてスコープが許すすべてにアクセスできるトークンという状態です。

このサーバーは、次の 3 つの面でそのギャップを埋めます。

• トリミングされたペイロード。 レスポンスは実際に使用するフィールドにまで正規化されるため、 PR レビューで消費するコンテキストは生の REST レスポンスの数分の一で済みます。

• プロンプトではなくサーバー側のガードレール。 保護ブランチ、破壊的操作に対する confirm、 読み取り専用モードは、HTTP 呼び出しが送出される前に強制されます。

• 意図ごとに 1 つのツール。 汎用的な HTTP エスケープハッチの代わりに、レビュー、ブランチ、 パイプライン、Webhook のワークフローをカバーする 55 のツールを提供します。

flowchart LR
  A["MCP client<br/>(Claude Code, Inspector)"] -->|stdio| B["bitbucket-mcp"]
  B --> C{"Guards"}
  C -->|"read only, confirm,<br/>protected branch,<br/>workspace lock"| D["Bitbucket Cloud<br/>REST API"]
  C -.->|refused before<br/>the HTTP call| A
  B --> E["git over SSH<br/>or HTTPS"]
  E --> F["Repository"]
  D -->|normalized,<br/>trimmed response| A

Related MCP server: Bitbucket MCP

インストール

このパッケージは npm に @marcusyoda/bitbucket-mcp として公開されています。

要件

• Node >= 20

• スコープ付き Atlassian API トークン（認証 を参照）

• SSH 経由の git_* ツール用に Bitbucket に登録された SSH キー。代わりに HTTPS 版を使用する場合はオプションです。

オプション 1: npx（インストール不要）

最も速い方法です。MCP クライアントをパッケージに向けて、npx に解決させます。

npx -y @marcusyoda/bitbucket-mcp

オプション 2: グローバルインストール

npm install -g @marcusyoda/bitbucket-mcp
# or: pnpm add -g @marcusyoda/bitbucket-mcp
bitbucket-mcp

オプション 3: ソースから

git clone https://github.com/marcusyoda/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install
pnpm build          # dist/index.js

MCP クライアントに登録する

Claude Code（CLI 経由）

claude mcp add bitbucket \
  --env BITBUCKET_EMAIL=you@example.com \
  --env BITBUCKET_API_TOKEN=your-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- npx -y @marcusyoda/bitbucket-mcp

任意のクライアント（.mcp.json 経由）

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@marcusyoda/bitbucket-mcp"],
      "env": {
        "BITBUCKET_EMAIL": "you@example.com",
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_DEFAULT_REPO": "your-repo-optional"
      }
    }
  }
}

代わりにソースから実行しますか? コマンドをビルド済みエントリポイントに置き換えてください。

{ "command": "node", "args": ["/abs/path/to/bitbucket-mcp/dist/index.js"] }

get_current_user を呼び出して接続を確認します。トークンのラウンドトリップが行われ、Bitbucket の ID が返されます。

認証

認証は email:api_token を使用した HTTP Basic です。スコープ付き API トークンは id.atlassian.com > Manage account > Security > API tokens で作成します。

トークンスコープ（詳細なピッカー。使用するものだけを作成）:

変数ツール（*_variable*、list_deployment_*）には admin:repository:bitbucket が必要です。このスコープを省略しても問題ありません。該当ツールは 403 を返し、それ以外はすべて正常に動作し続けます。

根拠と完全な権限決定記録は PERMISSIONS.md にあります。

環境変数

ローカル実行用に .env.example を .env にコピーしてください。これをコミットしてはいけません。

パッケージの .env は、環境に BITBUCKET_API_TOKEN が存在しない場合にのみ読み込まれます。これにより、プロジェクトごとの認証情報を注入するランチャーが常に優先され、別のワークスペースの迷子の .env が注入されたトークンを上書きすることは決してありません。

セーフティモデル

• BITBUCKET_READ_ONLY=true は、API に到達する前にすべての書き込みツールと破壊的ツールをブロックします。

• 破壊的ツール（merge、decline、delete_*、stop_pipeline、git_commit、git_push、インライン PR コメント）には confirm: true が必要です。

• secured 変数の作成にも confirm: true が必要です。

• セキュア変数の値は API 上書き込み専用で、返されたりログに記録されたりすることはありません。

• 保護ブランチ（BITBUCKET_PROTECTED_BRANCHES、デフォルトは main,dev）は直接変更がハードブロックされます。git_push、git_rebase（チェックアウト時）、delete_branch、create_branch は、confirm があっても保護ブランチをターゲットにしません。変更は PR 経由で取り込みます。保護ブランチへの merge_pull_request は confirm: true で許可されます。

• ワークスペースロック。 BITBUCKET_LOCK_WORKSPACE=true の場合、別のワークスペースを指定する呼び出しは拒否されます。1 つのインストールから複数のクライアントにサービスを提供するマシン向けに作られています。

ツール

すべてのツールは、環境変数のデフォルトを上書きするオプションの workspace と repo を受け付けます。

リポジトリとメタ: get_current_user、list_repositories、get_repository、create_repository

プルリクエスト: list_pull_requests、get_pull_request、get_pull_request_diff、get_pull_request_activity、create_pull_request、update_pull_request、approve_pull_request、unapprove_pull_request、request_changes_pull_request、decline_pull_request (confirm)、merge_pull_request (confirm)、list_pr_commits、get_diff

コメント: list_pr_comments、add_pr_comment (inline は confirm が必要)、reply_pr_comment、update_pr_comment、delete_pr_comment (confirm)、resolve_comment、react_pr_comment (実験的)

ブランチ、ソース、git: list_branches、get_branch、create_branch、delete_branch (confirm)、get_file_source、list_directory、clone_repo、clone_repo_https、git_commit (confirm)、git_rebase、git_push (confirm)、git_push_https (confirm)。すべてのプッシュツールとブランチツールは保護ブランチを拒否します。

パイプライン: list_pipelines、get_pipeline、get_pipeline_steps、get_pipeline_step_log、trigger_pipeline、stop_pipeline (confirm)

変数: list_repo_pipeline_variables、upsert_repo_pipeline_variable、delete_repo_pipeline_variable (confirm)、list_workspace_variables、list_deployment_environments、list_deployment_variables、upsert_deployment_variable、delete_deployment_variable (confirm)

Webhook: list_webhooks、get_webhook、create_webhook、update_webhook、delete_webhook (confirm)

git 用の SSH または HTTPS

clone_repo、git_commit、git_rebase、git_push はトークンではなくSSH キーを使用します。SSH が利用できない場合、clone_repo_https と git_push_https は username:token で認証し、BITBUCKET_USERNAME が必要です。保護ブランチのガードは両方のトランスポートに適用されます。

既知の制限

• react_pr_comment は実験的です。 PR コメントへの絵文字リアクションは、Cloud ではなく Bitbucket Data Center 向けにドキュメント化されています。このツールはベストエフォートのエンドポイントをターゲットにしており、ワークスペースがサポートしていない場合はエラーを返す可能性があります。

• resolve_comment は、リポジトリでコメントスレッドの解決が利用可能であることに依存します。

• カスタムパイプラインが期待する変数を一覧表示するエンドポイントはありません。その情報は bitbucket-pipelines.yml に含まれており、get_file_source で読み取ってください。

• 保存された変数の値を読み戻すには管理者スコープが必要です。

開発

pnpm install
pnpm dev         # tsx watch
pnpm typecheck
pnpm build       # tsup, ESM
pnpm inspect     # build and open the MCP Inspector

プロジェクトのルールと規約は CLAUDE.md にあります。コントリビューションは issue ファーストのワークフローに従います。すべてのコミットはヘッダーに type(scope): subject [#N] の形式で issue をリンクします。

利用する

MIT ライセンスです。文字通り、仕事で使う、商用で使う、フォークする、独自のツールにベンダリングする、名前を変更する、すべて自由です。許可を求める必要も、ライセンス表示を維持する以外の帰属の儀式もありません。手書きの REST 呼び出しを書く午後を 1 回節約できれば、それだけで元が取れています。

ツールが足りない、またはこれがカバーしていない Bitbucket エンドポイントに遭遇しましたか? issue を開いてください。プルリクエストも歓迎します。唯一のルールは、すべてのコミットがヘッダーに type(scope): subject [#N] の形式で issue をリンクすることです。

LICENSE を参照してください。