MCP Server for Bitbucket API

Bitbucket MCP サーバー

Bitbucket API 操作用の MCP サーバーです。Claude Code、Claude Desktop、Cursor、および MCP 対応のあらゆるクライアントで動作します。

言語バージョン

このリポジトリには、TypeScript と Python の実装が含まれています。

バージョン	ディレクトリ	ステータス	インストール
TypeScript	/typescript	✅ 推奨（Smithery）	npm install -g mcp-server-bitbucket
Python	/python	✅ 安定	pipx install mcp-server-bitbucket

注：Smithery へのデプロイには TypeScript 版が使用されます。どちらのバージョンも同じ機能を提供します。

TypeScript ではパッチ適用済みの Node.js 22.23.4 または 24.22.1 を、Python では Python 3.11 以降を使用してください。 HTTP リクエストの上限設定と再現可能なイメージビルドについては、セキュリティ更新を参照してください。

機能

• リポジトリ：取得、作成、削除、一覧表示、更新（プロジェクトへの移動、名前の変更）
• プルリクエスト：作成、取得、一覧表示、マージ、承認、却下、変更のリクエスト、コメント、差分
• パイプライン：実行、ステータスの取得、一覧表示、ログの表示、停止
• ブランチ：一覧表示、取得
• プロジェクト：一覧表示、取得
• コミット：一覧表示、詳細の取得、ブランチ間の比較／差分
• コミットステータス：ビルドステータスの取得、ステータスの作成（CI/CD 統合）
• デプロイ：環境の一覧表示、環境の詳細取得、デプロイ履歴
• Webhook：一覧表示、作成、取得、削除
• タグ：一覧表示、作成、削除
• ブランチ制限：ブランチ保護ルールの一覧表示、作成、削除
• ソースの閲覧：クローンせずにファイルを読み取り、ディレクトリを一覧表示
• リポジトリ権限：ユーザーとグループの権限を管理
• パイプライン変数：CI/CD 環境変数を管理
• MCP プロンプト：再利用可能なワークフローテンプレート（コードレビュー、リリースノートなど）
• MCP リソース：閲覧可能なワークスペースデータ

クイックスタート

TypeScript（Smithery 向けに推奨）

# Install globally
npm install -g mcp-server-bitbucket

# Or run directly with npx
npx mcp-server-bitbucket

Python

# Install with pipx
pipx install mcp-server-bitbucket

# Configure Claude Code
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e [email protected] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

インストールガイド全文 - API トークンの作成、権限の設定、トラブルシューティングを含みます。

ホステッド

サーバーを自分で実行したくない場合は、Fronteir AI でホステッド環境を利用できます。

設定

環境変数

変数	必須	説明
BITBUCKET_WORKSPACE	✅	Bitbucket ワークスペースのスラッグ
BITBUCKET_EMAIL	✅（Basic 認証）	Basic 認証に使用するアカウントのメールアドレス
BITBUCKET_API_TOKEN	✅	Atlassian API トークン（Basic 認証）
BITBUCKET_OAUTH_TOKEN		Authorization: Bearer として送信するアクセストークン
BITBUCKET_AUTH_TYPE		認証方式を指定：basic または bearer（自動検出）
API_TIMEOUT		リクエストのタイムアウト（秒、デフォルト：30）
MAX_RETRIES		レート制限時の最大再試行回数（デフォルト：3）

認証モード

Bitbucket Cloud には2種類の認証情報ファミリーがあり、認証方式は共通ではありません。

認証情報	ヘッダー	設定
Atlassian API トークン（ATATT...）、個人アカウントに紐付け	Authorization: Basic base64(email:token)	BITBUCKET_EMAIL + BITBUCKET_API_TOKEN
ワークスペース／プロジェクト／リポジトリのアクセストークン（ATCTT...）、ワークスペースが所有	Authorization: Bearer <token>	BITBUCKET_OAUTH_TOKEN

アクセストークンは Basic 認証で401 を返すため、サーバーはモードを自動的に選択します。

1. BITBUCKET_AUTH_TYPE が設定されている場合は、常にその値が優先されます。
2. BITBUCKET_OAUTH_TOKEN が設定されている場合、または BITBUCKET_EMAIL が設定されていない場合は、bearer が使用されます。
3. それ以外の場合は basic が使用されます（個人用 API トークンのデフォルト）。

Bearer の例 — 個人アカウントを介さず、会社が所有するワークスペースアクセストークンを使用する場合：

claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_OAUTH_TOKEN=your-workspace-access-token \
  -- npx mcp-server-bitbucket

リモートサーバーの保護（OAuth）

stdio サーバーはユーザー自身の認証情報を使ってユーザーのマシン上で実行されるため、保護は必要ありません。リモートデプロイでは事情が異なります。1つの共有認証情報を保持して、アクセスしたユーザーに提供するため、外部の認可サーバー（Microsoft Entra ID、Okta、Auth0 など）が発行したベアラートークンで /mcp へのアクセスを制限できます。

変数	説明
MCP_OAUTH_ISSUER	トークン発行者。例：https://login.microsoftonline.com/<tenant>/v2.0
MCP_OAUTH_AUDIENCE	想定される aud クレーム。例：api://bitbucket-mcp
MCP_OAUTH_JWKS_URI	署名キー（省略時は発行者から導出）
MCP_OAUTH_REQUIRED_SCOPE	トークンに必要なスコープ。例：mcp.access
MCP_PUBLIC_URL	このサーバーの公開 URL。リソースとして通知されます

MCP_OAUTH_ISSUER と MCP_OAUTH_AUDIENCE の両方が設定されていない限り、保護は無効です。そのため、既存のデプロイには影響しません。設定すると、サーバーは次のように動作します。

• 認証されていない /mcp リクエストに対し、/.well-known/oauth-protected-resource を示す WWW-Authenticate ヘッダーとともに 401 を返します。これにより MCP クライアントは OAuth フローを開始します。
• 認可サーバーを示すメタデータドキュメント（RFC 9728）を提供します。
• 各リクエストの JWT を検証します。発行者の JWKS による署名検証に加え、iss、aud、有効期限を確認します。また、有効なトークンに必要なスコープがない場合は 403 insufficient_scope を返します。
• /health は公開したままにするため、プラットフォームのプローブは引き続き動作します。

この仕組みで制御できるのは、サーバーを利用できるユーザーです。リクエストは引き続きサーバー自身の認証情報で Bitbucket に送信されるため、個々のユーザーに操作を紐付けることはできません。

Claude Code CLI

# TypeScript version
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e [email protected] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- npx mcp-server-bitbucket

# Python version
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e [email protected] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

Cursor IDE

~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["mcp-server-bitbucket"],
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_EMAIL": "[email protected]",
        "BITBUCKET_API_TOKEN": "your-api-token"
      }
    }
  }
}

利用可能なツール（合計58個）

リポジトリ

ツール	説明
list_repositories	リポジトリを一覧表示および検索します
get_repository	リポジトリの詳細を取得します
create_repository	新しいリポジトリを作成します
delete_repository	リポジトリを削除します
update_repository	リポジトリの設定を更新します

プルリクエスト

ツール	説明
list_pull_requests	PR を一覧表示します
get_pull_request	PR の詳細を取得します
create_pull_request	新しい PR を作成します
merge_pull_request	PR をマージします
approve_pr	PR を承認します
unapprove_pr	承認を取り消します
request_changes_pr	変更をリクエストします
decline_pr	PR を却下します
list_pr_comments	コメントを一覧表示します
add_pr_comment	コメントを追加します
get_pr_diff	差分を取得します

パイプライン

ツール	説明
list_pipelines	最近の実行を一覧表示
get_pipeline	ステータスを取得
get_pipeline_logs	ログを表示
trigger_pipeline	実行をトリガー（カスタムパイプラインとコミットトリガーに対応）
stop_pipeline	パイプラインを停止
list_pipeline_variables	変数を一覧表示
get_pipeline_variable	変数を取得
create_pipeline_variable	変数を作成
update_pipeline_variable	変数を更新
delete_pipeline_variable	変数を削除

trigger_pipeline のパラメーター

パラメーター	型	説明
repo_slug	string	リポジトリのスラッグ（必須）
branch	string	実行対象のブランチ（デフォルト：main）。commit とは同時に指定できません
commit	string	実行対象のコミットハッシュ。branch とは同時に指定できません
custom_pipeline	string	bitbucket-pipelines.yml の custom: セクションにある名前
variables	array	[{key, value, secured?}] 形式の変数

例：

# Default pipeline on main
trigger_pipeline(repo_slug="my-repo")

# Custom pipeline
trigger_pipeline(repo_slug="my-repo", custom_pipeline="deploy-staging")

# Custom pipeline on specific commit with variables
trigger_pipeline(
    repo_slug="my-repo",
    commit="abc123def",
    custom_pipeline="deploy-prod",
    variables=[
        {"key": "ENV", "value": "production"},
        {"key": "SECRET", "value": "xxx", "secured": True}
    ]
)

ブランチ、コミット、タグ

ツール	説明
list_branches	ブランチを一覧表示
get_branch	ブランチの詳細を取得
list_commits	コミットを一覧表示
get_commit	コミットの詳細を取得
compare_commits	ブランチを比較
get_commit_statuses	ビルドのステータスを取得
create_commit_status	CI ステータスを報告
list_tags	タグを一覧表示
create_tag	タグを作成
delete_tag	タグを削除

その他...

• デプロイメント：list_environments、get_environment、list_deployment_history
• Webhook：list_webhooks、create_webhook、get_webhook、delete_webhook
• ブランチ制限：list_branch_restrictions、create_branch_restriction、delete_branch_restriction
• ソースの閲覧：get_file_content、list_directory
• 権限：ユーザーとグループの権限管理（8 個のツール）
• プロジェクト：list_projects、get_project

MCP プロンプト

再利用可能なワークフローテンプレート：

プロンプト	説明
code_review	包括的な PR コードレビュー
release_notes	バージョン間の変更履歴を生成
pipeline_debug	失敗した CI/CD パイプラインをデバッグ
repo_summary	リポジトリのステータス全体を把握

MCP リソース

閲覧可能なワークスペースデータ：

リソース URI	説明
bitbucket://repositories	すべてのリポジトリを一覧表示
bitbucket://repositories/{repo}	リポジトリの詳細
bitbucket://repositories/{repo}/branches	ブランチ一覧
bitbucket://repositories/{repo}/pull-requests	オープン中の PR
bitbucket://projects	すべてのプロジェクトを一覧表示

開発

TypeScript

cd typescript
npm install
npm run build
npm run dev  # Watch mode

Python

cd python
uv sync
uv run python -m src.server

Bitbucket API トークンの作成

1. Bitbucket でリポジトリに移動します
2. Repository settings > Access tokens に移動します
3. Create Repository Access Token をクリックします
4. 権限を選択します：
   • Repository：Read、Write、Admin、Delete
   • Pull requests：Read、Write
   • Pipelines：Read、Write
5. トークンをすぐにコピーします

仕事での利用について

チームが会社の Bitbucket に対してこれを実行している場合は、ぜひお知らせください。次に何を構築するかの判断に役立ち、実際のデプロイメントで発生した課題を優先して確認します。

この関連で、次の 2 種類の作業を引き受けています：

• MCP サーバーがない社内システム向けの MCP サーバー。 こちらと同じ構成で、お客様独自の API に対応します。
• MCP のデプロイメントがセキュリティレビューを通過するための支援 — スコープ、トークンの取り扱い、トランスポートのセルフホスト。

issue を作成するか、[email protected] までご連絡ください。

作者

ジャビエル・アギラール が構築・保守しています — エージェントシステムと MCP 統合に取り組む AI エンジニアです。このサーバーを構築した経緯と理由については、こちらをご覧ください。

ライセンス

MIT