mcp-bitbucket

AIエージェントとその隣にいる人間のためのBitbucket Server。クローンなしでプルリクエストとその差分を読み、レビューを下書きして判定付きで公開し、ブロッキングタスクを投稿し、コードとコミットを閲覧し、プルリクエストをオープン、マージ、または辞退できます — MCPクライアントから、シェルから、または独自のTypeScriptから。

Bitbucket Server / Data Center のみ対応。Bitbucket Cloudはサポートされていません。

パッケージ

Claude Code / Claude Desktopのツール使用 → mcp。ターミナル、スクリプト、CI、コマンドを実行するエージェント → cli。他の何かを構築する → core。これらは同じ認証情報を読み、並べてインストールされます。

Related MCP server: mcp-server-atlassian-bitbucket

前提条件

• Node.js 18+、pnpm 10+（corepack enable）

• Bitbucket Serverのパーソナルアクセストークン — プロフィール → アカウント管理 → HTTPアクセストークン、リポジトリ読み取り + プルリクエスト書き込み権限

• bb login（OSキーリング）の場合のみ: sudo apt install -y libsecret-1-0 gnome-keyring。すべてのコマンドはBITBUCKET_TOKENからも動作します。

インストール

pnpm install
pnpm build        # core first, then mcp and cli

エントリポイント: packages/mcp/dist/index.js、packages/cli/dist/index.js。

クイックスタート

MCPサーバー

claude mcp add mcp-bitbucket \
  -e BITBUCKET_URL=https://bitbucket.example.com \
  -e BITBUCKET_TOKEN=your-personal-access-token \
  -- node /absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js

または.mcp.json内（${VAR}はClaude Codeによって展開されるため、シークレットはコミットされません）:

{
  "mcpServers": {
    "mcp-bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "${BITBUCKET_URL}",
        "BITBUCKET_TOKEN": "${BITBUCKET_TOKEN}"
      }
    }
  }
}

stdioの代わりにHTTPトランスポート: node packages/mcp/dist/index.js --http（ポート3000）またはMCP_HTTP_PORT=8080 node …。ルート: POST /mcp、GET /mcp（SSE）、DELETE /mcp。

bb CLI

pnpm --filter @mcp-bitbucket/cli link --global
bb login          # or export BITBUCKET_URL / BITBUCKET_TOKEN
bb whoami         # proves authentication — `bb ping` only proves reachability
bb pr get 42      # repository comes from the git origin remote

コマンドサーフェス: packages/cli/README.md または bb --help。

Claude Codeスキル

bash packages/skill/scripts/install.sh            # ~/.claude/skills/bitbucket-review
bash packages/skill/scripts/install.sh ./.claude  # project scope

bbがPATHにあり、解決可能な認証情報が必要です。

設定

環境変数。リポジトリルートの.envは自動的に読み込まれます（cp .env.example .env）。MCPサーバーは起動時にそれらを検証します。CLIは--url / --tokenも受け付け、これらがすべてに優先します。

制限

すべての数値上限はpackages/core/src/operations/caps.tsにあり、環境変数で上書き可能です: BITBUCKET_DIFF_MAX_CHARS（60000）、BITBUCKET_DIFF_HEAD_RATIO（0.6）、BITBUCKET_DIFF_CONTEXT_LINES（3）、BITBUCKET_DIFF_FETCH_MAX_CHARS（12000000）、BITBUCKET_DIFF_CACHE_ENTRIES（4）、BITBUCKET_CHANGED_FILES_MAX_ITEMS（1000）、BITBUCKET_CHANGED_FILES_STATS_MAX_FILES（500）。切り詰めは決して黙って行われません — メモは上限を引き上げるパラメータと変数を指定し、省略されたハンクヘッダーをすべてリストします。

権限

2つの独立したガード。

MCP_PERMISSION_MODE — MCPサーバーのみ。 すべてのツールはpackages/mcp/src/permissions.tsでread、write、destructiveに分類されます。禁止されたツールはListToolsから隠され、名前で呼び出された場合も拒否されます。

CLIはこれを読みません。readonlyデプロイメントはbb review mergeを止めません。

リポジトリ許可リスト — 両方のエントリポイント。 BITBUCKET_ALLOWED_PROJECTS / BITBUCKET_ALLOWED_REPOSはカンマ、セミコロン、またはスペース区切りのパターンを受け取ります: PROJ、PROJ/*、PROJ/repo-a。チェックは共有クライアント内でソケットが開く前に実行されるため、すべてのツールとすべてのbbコマンドがそれを継承します。未設定はすべてのリポジトリを意味します。大文字小文字を区別しません。個人リポジトリはプロジェクト~usernameです。不正なパターンは破棄され、決して拡大されません — 不正なパターンだけで構成された値は何も許可しません。

ツール

29のMCPツール: 読み取り17、書き込み9、破壊的3。完全なパラメータはdocs/tools.mdにあります。

注目すべきデフォルト

• 解決済みの議論は非表示。 get_pull_request_comments / bb comment lsは解決済みのスレッドとタスクを表示するためにincludeResolved（--include-resolved）が必要です。応答は非表示にした数を示します。明示的なstateフィルターはデフォルトを上書きします。

• レビューは下書きされ、投稿されません。 add_pr_draft_comment / bb review draftは不可視のコメントを保存します。submit_pr_reviewは保留中のすべてのコメントを判定付きで1つの通知として公開します。pending: false（--no-pending）は即座に投稿します。discard_pr_draft_reviewは下書きを破棄します。

• bb ping ≠ 認証。 /application-propertiesは多くのインスタンスで匿名で200を返します。bb whoamiが認証チェックです。

開発

pnpm build | typecheck | test | lint | format | clean
pnpm dev:mcp                 # MCP server from source (tsx)
pnpm cli pr ls               # bb from source
pnpm --filter @mcp-bitbucket/core test

アダプタが乖離しないようにするレイヤリングルール:

• coreはMCPやCLIについて何も知らない — MCP SDKもyargsもstdoutもありません。操作はクライアントとパラメータを受け取り、構造化データを返すか例外を投げます。

• アダプタは入力検証と出力形式を担当 — mcpではzodとMCP結果形式、cliではyargsとテキスト/--json。どちらもcoreに漏れません。

• エラーメッセージはcoreに一度だけ書かれる、{projects} / {login}スタイルのプレースホルダーを使い、各アダプタが独自の語彙でレンダリングします — 同じ失敗がモデルには「list_projectsを使え」、あなたには「bb project lsを使え」と伝えます。

• 新しい機能はcoreの操作とフォーマッタ、そしてmcpとcliそれぞれの薄いアダプタです。

Docker

イメージはMCPサーバーのみを含みます。

docker build -t mcp-bitbucket .
docker run -i --rm -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… mcp-bitbucket
docker run --rm -p 3000:3000 -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… -e MCP_HTTP_PORT=3000 mcp-bitbucket

トラブルシューティング

docs/troubleshooting.md。最も一般的な3つ: クライアントリストからツールが欠けている場合、MCP_PERMISSION_MODEがそれを隠していることを意味します（認識されない値は29すべてを隠します）。Refused: … outside the configured repository allowlistは許可リストがそのリポジトリをカバーしていないことを意味します。Web UIよりコメントが少ない場合は、解決済みスレッドが非表示になっています。

制限事項

• Bitbucket Serverのみ。Bitbucket Cloud、OAuth/SSO、アプリパスワードはありません。

• bb loginはOSキーリングにのみ認証情報を保存します — 平文ストアも--passwordもありません。

• Webhookやイベント駆動モードはありません。サーバーはツール呼び出しに応答します。

• 差分はサーバーでレンダリングされた統合差分テキストです。差分にアンカーされたインラインコメントは公開されません。

• search_codeはインスタンスのコードインデックスが必要です: デフォルトブランチ、完全一致、正規表現なし。

• MCP_PERMISSION_MODEはMCPサーバーのみを制限します。許可リストは両方を制限します。