bitbucket-mcp-server

@droplinkperformance/bitbucket-mcp-server

Bitbucket Cloud 向けの、プロバイダーに依存せず、AI レビューを最優先とする Model Context Protocol（MCP）サーバーです。

このサーバーの主な価値は、Bitbucket API に対する CRUD ではなく、AI を活用したコードレビューとプルリクエストの分析です。主要な依存関係（SCM アクセス、キャッシュ、トークンストレージ、レート制限、LLM、イベント）はすべてプロバイダーに依存しないインターフェースの背後に隠されているため、ユースケース、エージェント、ドメインコントラクトを変更せずに、同じビジネスロジックを後から GitHub／GitLab／Azure DevOps や OpenAI／Anthropic／Gemini／Bedrock に対応させることができます。

ステータス：Phase 1。ロードマップを参照してください。

機能（Phase 1）

• 2 種類のトランスポートに対応：stdio（Cursor／Claude Desktop）およびStreamable HTTP（Node http、リモート／本番環境向け）。
• ToolRegistry によるツールの自動検出 — 手動登録は不要です。
• すべてのツールで明示的な BitbucketContext（workspace ＋ オプションの repository）を使用 — 複数ワークスペースに対応しています。
• 堅牢な BitbucketClient：認証の注入、自動ページネーション、リトライ／バックオフ、レート制限の処理、キャッシュ、シークレットのマスキングに対応しています。
• 2 種類の認証方式：OAuth 2.0（認可コードフロー、ローテーションするリフレッシュトークンの永続化に対応）およびBearer トークン。
• CodeReviewAgent によるAI コードレビュー（analyze_pull_request）。大規模な PR を分割し、標準の ReviewResult を返します。
• プラグイン可能な LLM プロバイダー（OpenAI／Anthropic／Gemini／Bedrock）、キャッシュ（メモリ／Redis）、トークンストア（ファイル／メモリ／Redis）。

ツール

ツール	説明
get_current_user	認証済みユーザーを取得します。
list_pull_requests	PR を一覧表示します（状態／クエリによる絞り込みに対応）。
get_pull_request	ID を指定して PR を取得します。
create_pull_request	PR を作成します。
update_pull_request	オープン中の PR のタイトルや説明を編集します。
get_pull_request_diff	未加工の統合差分を取得します。
get_pull_request_files	変更されたファイルと行数の統計を取得します。
get_pull_request_comments	PR のコメントを取得します。
comment_pull_request	コメントを追加します（インラインコメントは任意です）。
analyze_pull_request	標準の ReviewResult を返す AI レビューを実行します。

すべてのツール入力で workspace を指定できます（BITBUCKET_DEFAULT_WORKSPACE が設定されている場合は省略可能です）。該当する場合は repository も指定できます。

アーキテクチャ

src/
  index.ts            entry: chooses transport
  container.ts        composition root (the only place wiring concretes)
  mcp/                McpServer + ToolRegistry (auto-discovery) + transports
  tools/              thin MCP adapters (*.tool.ts) -> call exactly one use-case
  application/        use-cases (CQRS-ish: command|query) with Input/Output DTOs
  agents/             autonomous workflows implementing Agent<TInput,TOutput>
  domain/             provider-agnostic types, repository contracts, ReviewResult
  repositories/bitbucket/  Bitbucket implementations of the contracts
  clients/bitbucket/  resilient REST client
  auth/               AuthProvider (+ token/oauth) and TokenStore implementations
  cache/              CacheProvider (+ memory/redis)
  ratelimit/          RateLimitStrategy (+ bitbucket)
  llm/                LlmProvider (+ openai/anthropic/gemini/bedrock)
  events/             EventBus (+ in-memory)
  services/           reusable services (masking, chunking)
  telemetry/          OpenTelemetry bootstrap + metrics
  infrastructure/     config, logger, http, attachments
  shared/             errors, result envelope, http-status, BitbucketContext

フロー：tool -> use-case -> (agent | repository contract) -> repositories/bitbucket -> BitbucketClient。エージェントは LlmProvider と EventBus も使用できます。ツールにビジネスロジックは含まれません。

要件

• Node.js 23+

インストール

@droplinkperformance/bitbucket-mcp-server として公開されています。

npx -y @droplinkperformance/bitbucket-mcp-server

ソースからインストールする場合：

npm install
npm run build

リリース

main へのマージ時に .github/workflows/release.yml が実行されます。テスト、ビルドの後、semantic-release が実行されます。バージョンの更新と npm への公開は、マージに Conventional Commits が含まれる場合にのみ行われます。

コミット	バージョン更新
fix:	パッチ
feat:	マイナー
BREAKING CHANGE / feat!:	メジャー

その他のメッセージでは公開はスキップされます。GitHub シークレット NPM_TOKEN（droplinkperformance 組織の npm Automation トークン）が必要です。

npm へのリリースが成功すると、同じワークフローでそのバージョンが npm レジストリに表示されるまで待機した後、MCP Registry に io.github.droplinkperformance/bitbucket-mcp-server としてメタデータを公開します（OIDC を使用し、追加のシークレットは不要です）。新しいリリースを作成せずに、現在の package.json のバージョンの MCP メタデータを再公開するには、ワークフローを手動で実行し、Publish mcp only を選択してください。github.com/mcp はこのレジストリから同期します。サーバーが表示されない場合は、[email protected] までメールでお問い合わせください。

最初のリリースを 0.x にとどめるには、最初の Conventional Commit によるマージの前に現在のコミットにタグを付けてください（git tag v0.1.0 && git push origin v0.1.0）。そうしない場合、semantic-release は 1.0.0 から開始します。

設定

.env.example を .env にコピーし、値を入力します。Node の組み込みフラグを使って読み込みます。

node --env-file=.env dist/index.js

主な変数：

変数	デフォルト	説明
MCP_TRANSPORT	stdio	stdio または http。
HTTP_HOST / HTTP_PORT	0.0.0.0 / 3000	HTTP トランスポートのバインド先。
BITBUCKET_DEFAULT_WORKSPACE	–	ツールで workspace が指定されていない場合のフォールバック。
BITBUCKET_ACCESS_TOKEN	–	API トークン（ATATT…）、アプリパスワード、または OAuth アクセストークン
BITBUCKET_EMAIL	–	API トークン（ATATT…）で必須です — Atlassian アカウントのメールアドレス
BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET	–	OAuth（アクセストークンがない場合）で必須です。
BITBUCKET_REFRESH_TOKEN	–	ヘッドレス OAuth 用の任意のシード値。
TOKEN_STORE	file	file | memory | redis。
CACHE_PROVIDER	memory	memory | redis。
LLM_PROVIDER	openai	openai | anthropic | gemini | bedrock。
MAX_FILES_PER_CHUNK / MAX_DIFF_LINES_PER_CHUNK	50 / 5000	大規模 PR のチャンク分割しきい値。
OTEL_ENABLED	false	有効にしない限り、メトリクスは何も記録されません。

認証

Bearer（OAuth アクセストークン）： BITBUCKET_ACCESS_TOKEN のみを設定します（ATATT ではないトークン）。

API トークン（推奨、ATATT…）： BITBUCKET_ACCESS_TOKEN と BITBUCKET_EMAIL（Bitbucket → 個人設定 → メールエイリアスにある Atlassian アカウントのメールアドレス）を設定します。API トークンでは Bearer ではなく HTTP Basic 認証を使用します。

アプリパスワード（レガシー、2026 年 6 月まで）： BITBUCKET_ACCESS_TOKEN と BITBUCKET_USERNAME（Bitbucket のユーザー名）を設定します。

OAuth 2.0（認可コード）： BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET を設定します。トークンは設定した TOKEN_STORE に保存されます。Bitbucket はリフレッシュトークンをローテーションするため、サーバーはリフレッシュのたびに新しいトークンを保存します。ヘッドレスで起動する場合は、事前に取得した BITBUCKET_REFRESH_TOKEN を指定してください。

使用する Bitbucket OAuth エンドポイント：認可 https://bitbucket.org/site/oauth2/authorize、トークン https://bitbucket.org/site/oauth2/access_token。認可 URL は OAuthProvider.buildAuthorizeUrl() で構築でき、返された ?code= は OAuthProvider.loginWithCode(code) で交換できます。

LLM プロバイダー

LLM_PROVIDER と、対応するキーを設定します。

LLM_PROVIDER=openai      # OPENAI_API_KEY
LLM_PROVIDER=anthropic   # ANTHROPIC_API_KEY
LLM_PROVIDER=gemini      # GEMINI_API_KEY
LLM_PROVIDER=bedrock     # AWS creds + BEDROCK_MODEL_ID (needs @aws-sdk/client-bedrock-runtime)

ioredis（Redis プロバイダー）と @aws-sdk/client-bedrock-runtime（Bedrock）はオプションで、遅延読み込みされます — 選択した場合にのみ必要です。

実行

stdio

MCP_TRANSPORT=stdio node --env-file=.env dist/index.js

Streamable HTTP

MCP_TRANSPORT=http HTTP_PORT=3000 node --env-file=.env dist/index.js
# health:   GET  http://localhost:3000/health
# endpoint: POST http://localhost:3000/mcp

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Cursor

~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BITBUCKET_ACCESS_TOKEN": "ATATT-your-api-token",
        "BITBUCKET_EMAIL": "[email protected]",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_ACCESS_TOKEN": "your-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

開発

npm run dev          # tsx watch (stdio)
npm run typecheck
npm run lint
npm test
npm run test:coverage

ロードマップ

• フェーズ 1（今回のリリース）： 認証、抽象化、BitbucketClient、ツールの自動検出、PR ツール、analyze_pull_request。
• フェーズ 2： Pipelines + 全文検索対応のページ分割ログ、pipeline-investigator エージェント、auto_review_pull_request（ドライラン / インラインコメントの公開）。
• フェーズ 3： 残りの CRUD — リポジトリ、コミット、ブランチ、タグ、課題、ワークスペース、メンバー、検索。
• フェーズ 4： analyze_dotnet_pull_request（dotnet-review エージェント）、高度なエージェント、自動化ワークフロー。
• フェーズ 5： Docker、Compose、Helm、本番環境へのデプロイガイド。

ライセンス

MIT