Skip to main content
Glama
Bitbucket MCP Server

Bitbucket MCP Server

by inceon

Bitbucket MCP Server

License: MIT CI Node.js MCP

本番運用に重点を置いた Model Context Protocol サーバーで、Bitbucket Cloud および Bitbucket Server/Data Center からプルリクエストのメタデータと差分を取得し、オプトインでプルリクエストコメントにも対応します。

機能

  • Bitbucket Cloud とセルフホスト型 Bitbucket Server/Data Center をサポートします。

  • プルリクエストのメタデータ、差分、レビュー議論、一般/インラインコメントに特化したツールを公開します。

  • Bearer トークンと基本認証をサポートします。

  • Bitbucket が提供する場合、生の差分と構造化された変更ファイルデータの両方を返します。

  • 設定可能な glob パターンにより、生成されたファイル、フォルダー、またはファイルタイプを除外します。

  • UTF-8 文字を壊すことなく大きな差分に上限を設けます。

  • プロトコルを壊すログを stdout に書き出さず、stdio を使用します。

  • コメント作成はデフォルトで無効のままとし、プルリクエストの承認、マージ、その他の変更は行いません。

Related MCP server: Atlassian Bitbucket MCP Server

クイックスタート

対応する Node.js LTS リリース(Node.js 22 以降)が必要です。

git clone https://github.com/inceon/bitbucket-mcp.git
cd bitbucket-mcp
npm install
npm run build
cp .env.example .env

BITBUCKET_URL と BITBUCKET_TOKEN を MCP クライアント設定に設定し、コンパイル済みサーバーを node dist/index.js で起動してください。このサーバーは意図的に .env ファイルを自分で読み込みません。MCP クライアントが環境変数を直接渡す必要があります。

認証

Bearer 認証がデフォルトであり、Bitbucket Server/Data Center の個人アクセストークンに推奨されます:

BITBUCKET_URL=https://bitbucket.example.com/bitbucket
BITBUCKET_TOKEN=your-personal-access-token
BITBUCKET_AUTH_TYPE=bearer

基本認証が必要な Bitbucket Cloud API トークンまたはアプリパスワードの場合:

BITBUCKET_URL=https://api.bitbucket.org
BITBUCKET_TOKEN=your-api-token-or-app-password
BITBUCKET_AUTH_TYPE=basic
BITBUCKET_USERNAME=your-bitbucket-username

有効にするツールに必要な権限のみを認証情報に付与してください。コメント作成には、プルリクエストコメントを作成する権限が必要です。認証情報をコミットしたり、実際のトークンを issue レポートに記載したりしないでください。

環境変数

変数

必須

デフォルト

説明

BITBUCKET_URL

はい

-

Bitbucket のベース URL(例: https://api.bitbucket.org または https://bitbucket.example.com/bitbucket)

BITBUCKET_TOKEN

はい

-

API トークン、アプリパスワード、または個人アクセストークン

BITBUCKET_AUTH_TYPE

いいえ

bearer

bearer または basic

BITBUCKET_USERNAME

基本認証の場合

-

基本認証でトークンと組み合わせるユーザー名

BITBUCKET_MAX_DIFF_BYTES

いいえ

200000

rawDiff で返す UTF-8 バイト数の上限。通常より大きなコンテキストを扱うクライアントでは明示的に増やしてください

BITBUCKET_MAX_DIFF_INPUT_BYTES

いいえ

10000000

停止するまでに上流の生 diff から読み取る最大バイト数

BITBUCKET_MAX_JSON_BYTES

いいえ

10000000

任意の Bitbucket JSON 応答から読み取る最大バイト数

BITBUCKET_MAX_COMMENT_COUNT

いいえ

5000

ページをまたいで収集するプルリクエストコメントの最大数

BITBUCKET_MAX_COMMENT_PAGES

いいえ

100

追跡するプルリクエストコメントページの最大数

BITBUCKET_MAX_COMMIT_COUNT

いいえ

5000

ページをまたいで収集するプルリクエストコミットの最大数

BITBUCKET_MAX_COMMIT_PAGES

いいえ

100

追跡するプルリクエストコミットページの最大数

BITBUCKET_MAX_DIFF_FILES

いいえ

5000

ページをまたいで収集する構造化変更ファイルエントリの最大数

BITBUCKET_MAX_DIFF_PAGES

いいえ

100

追跡する構造化変更ファイルページの最大数

BITBUCKET_REQUEST_TIMEOUT_MS

いいえ

30000

各 Bitbucket HTTP リクエストの期限(ミリ秒)

BITBUCKET_IGNORE_PATTERNS

いいえ

-

すべての PR 差分から除外するカンマ区切りのファイル glob

BITBUCKET_ENABLE_WRITE_TOOLS

いいえ

false

Bitbucket を変更するツール(現時点では PR コメント作成)を許可するには true に設定します

サーバーは起動時エラーを stderr にのみ書き出し、Bitbucket HTTP エラースニペットから設定された認証情報をマスクします。

MCP 設定

Claude Desktop の設定:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org",
        "BITBUCKET_TOKEN": "your-token"
      }
    }
  }
}

Codex の config.toml 設定:

[mcp_servers.bitbucket]
command = "node"
args = ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"]

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://api.bitbucket.org"
BITBUCKET_TOKEN = "your-token"

利用可能なツール

get_pull_request

プルリクエストのメタデータ(説明、状態、作成者、レビュアー、ブランチ、タイムスタンプ、リンク)を返します。

{
  "name": "get_pull_request",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123
  }
}

get_pull_request_comments

既存の一般コメントとインラインコメントを、プロバイダー独自のコメントオブジェクトとして返します。レビュー指摘を投稿する前に、既存のフィードバックを考慮するために使用してください。設定された取得上限に達すると、commentsStatus.complete は false になり、理由は max_comments または max_pages になります。

get_pull_request_commits

現在プルリクエストにあるプロバイダー独自のコミットを返します。指摘の発端となったコミットを追跡したり、後続の作業で対処されているかを確認したりするために使用します。設定された取得上限に達すると、commitsStatus.complete は false になり、理由は max_commits または max_pages になります。

get_pull_request_diff

利用可能な場合、git スタイルのレビュー差分と構造化された変更ファイルを返します。

{
  "name": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJECT_KEY",
    "repository": "my-repository",
    "pull_request_id": 123,
    "ignore_patterns": ["dist/**", "**/*.generated.ts", "package-lock.json"],
    "path": "src/service.ts",
    "context": 5,
    "ignore_whitespace": true,
    "renames": true
  }
}

差分出力は、後方互換性のある JSON テキストと MCP の structuredContent の両方として利用でき、公開された出力スキーマを備えています。含まれるもの:

  • provider、pull_request_id、rawDiff、rawDiffBytes、rawDiffSource。rawDiffSource は、Cloud では provider_raw、ローカルで正規化された Server/Data Center 応答では server_structured になります。

  • truncated と truncationReason: 上流の Cloud 読み取り上限に達した場合は input_limit、フィルタリング後の結果が BITBUCKET_MAX_DIFF_BYTES を超えた場合は output_limit、Server/Data Center が構造化差分を切り詰め済みとマークした場合は provider_limit です。

  • オプションのコンパクトな files エントリには、path、正規化された status、およびリネームまたはコピーの場合の oldPath のみが含まれます。必須の filesStatus は完全性を報告します。complete が false の場合、理由は max_files、max_pages、または unsupported で、returned は実際に返されたフィルタリング済みエントリを反映します。

  • 除外が有効な場合のオプションの ignored メタデータ。

完全な結果:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 128,
  "rawDiffSource": "provider_raw",
  "files": [],
  "filesStatus": { "available": true, "complete": true, "returned": 0 },
  "truncated": false
}

上限付きの部分結果:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 200000,
  "rawDiffSource": "provider_raw",
  "files": [{ "path": "src/service.ts", "status": "modified" }],
  "filesStatus": {
    "available": true,
    "complete": false,
    "returned": 1,
    "reason": "max_pages"
  },
  "truncated": true,
  "truncationReason": "output_limit"
}

切り詰められた rawDiff は UTF-8 セーフなレビュー用プレフィックスであり、必ずしも完全な行、ハンク、または適用可能なパッチではありません。

構造化ファイルページは、完了するか、設定されたファイル数/ページ数の上限に達するまで追跡され、その後、プロバイダーのハッシュ、リンク、重複するパス構造を返すのではなく、コンパクトなレビューメタデータに正規化されます。利用できない diffstat または changes エンドポイントは、HTTP 404 の後にのみ報告されます。認可、レート制限、サーバー、不正な応答、タイムアウト、転送の失敗は、メタデータを黙って省略するのではなく、ツール呼び出しを失敗させます。

Cloud の rawDiff はプロバイダーの生の応答を保持します。Server/Data Center は構造化された /diff 応答を使用し、そのファイル、ハンク、セグメント、行を git スタイルのレビューテキストに正規化します。これにより、別の .diff エクスポート経路でのバージョン固有の失敗を回避できます。rawDiffSource はその違いを明示します。

path は両プロバイダーでサポートされており、大きなプルリクエストをファイル単位でレビューする推奨方法です。返される files メタデータは同じパスにスコープされます。renames は Cloud のみです。context は Cloud の context と Server/Data Center の contextLines に対応します。ignore_whitespace は Cloud の ignore_whitespace と Server/Data Center の whitespace=ignore-all に対応します。これらが指定されていない場合、プロバイダーのデフォルトは変更されません。

パターンはリポジトリ相対パスを使用し、*、**、? をサポートします。package-lock.json や *.png のように / を含まないパターンは、そのファイル名を任意の場所で照合します。末尾のスラッシュはディレクトリを再帰的に除外します。除外が有効な場合、応答には ignored.patterns、ignored.files、ignored.rawDiffFiltered が含まれます。rawDiffFiltered が false の場合、Cloud プロバイダーが安全にフィルタリングできない非 git 差分形式を返したことを意味します。コンテンツを黙って落とす代わりに、応答が保持されます。

add_pull_request_comment

プルリクエストに一般コメント、ファイルレベルコメント、またはインライン行コメントを作成します。この書き込み操作は、MCP サーバー環境で BITBUCKET_ENABLE_WRITE_TOOLS=true が設定されている場合にのみ利用できます。

一般コメント:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "The implementation looks good. Please add a regression test for the empty input case."
  }
}

追加された行へのインラインコメント:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "Please handle an empty value here.",
    "file_path": "src/service.ts",
    "line": 42,
    "line_type": "added"
  }
}

line_type には added、removed、context のいずれかを使用します。追加行はデフォルトで new 側、削除行はデフォルトで old 側、コンテキスト行はデフォルトで new になります。コンテキストコメントを old に配置するには、line_side を明示的に設定してください。ファイルレベルコメントには、行フィールドなしで file_path を指定します。Server/Data Center でリネームされたファイルの場合、source_file_path で以前のパスを指定できます。

認証された Bitbucket ユーザーがコメント作成者になります。MCP クライアントでツール呼び出しを承認する前に、対象のワークスペース、リポジトリ、プルリクエスト ID、コメントテキストを確認してください。

プロバイダーの動作

URL のホストがプロバイダーを決定します。bitbucket.org と api.bitbucket.org は Bitbucket Cloud を使用し、その他のすべてのホストは Server/Data Center を使用します。

Cloud URL は 1 つの /2.0 API プレフィックスに正規化され、以下を使用します:

  • /repositories/{workspace}/{repository}/pullrequests/{id}

  • /repositories/{workspace}/{repository}/pullrequests/{id}/diff

  • /repositories/{workspace}/{repository}/pullrequests/{id}/diffstat

  • /repositories/{workspace}/{repository}/pullrequests/{id}/comments (GET; 有効時は POST)

  • /repositories/{workspace}/{repository}/pullrequests/{id}/commits (GET)

Server/Data Center URL は /bitbucket などのコンテキストパスを保持し、1 つの /rest/api/1.0 プレフィックスに正規化して、以下を使用します:

  • /projects/{project}/repos/{repository}/pull-requests/{id}

  • /projects/{project}/repos/{repository}/pull-requests/{id}/diff(git スタイルのレビューテキストに正規化された構造化差分)

  • /projects/{project}/repos/{repository}/pull-requests/{id}/diff/{path}(パスにスコープされた構造化差分)

  • /projects/{project}/repos/{repository}/pull-requests/{id}/changes

  • /projects/{project}/repos/{repository}/pull-requests/{id}/comments (GET; 有効時は POST)

  • /projects/{project}/repos/{repository}/pull-requests/{id}/commits (GET)

オプションの diffstat または changes リクエストは、HTTP 404 の後に filesStatus.reason: "unsupported" を報告します。その他の HTTP、タイムアウト、転送、解析の失敗はツール呼び出しを失敗させ、不完全なメタデータが完全な応答と誤認されることを防ぎます。

Atlassian Rovo MCP

Atlassian は Cloud 専用の bitbucketPullRequest.diff アクションを文書化していますが、その引数スキーマ、出力形式、ページネーション、フィルタリング、切り詰め契約は公開していません。したがって、このサーバーは直接の Bitbucket API を正規の情報源として維持します。Rovo アダプターは、実際の tools/list スキーマと制御された diff レスポンスを検証した後にのみ追加すべきであり、明示的に設定された状態を維持する必要があり、Server/Data Center サポートを置き換えることはできません。Atlassian のサポート対象ツールページ を参照してください。

ロードマップ

今後のリリースで計画されている領域は次のとおりです。

  • リトライ処理と、より明確なレート制限診断を追加する。

  • プロバイダー固有のフィールドへのアクセスを維持しつつ、正規化されたプルリクエスト出力を提供する。

  • プルリクエストの一覧表示とビルドステータス取得のための読み取り専用ツールを追加する。

  • stdio をデフォルトに保ちながら、オプションの Streamable HTTP トランスポートを提供する。

  • より簡単なインストールおよびアップグレードパスでバージョン付きリリースを公開する。

書き込み操作はデフォルトで無効のままです。承認、マージ、その他の影響の大きい Bitbucket 操作は計画されていません。アイデアや実装提案は GitHub issues を通じて歓迎します。

開発

npm run dev        # Run directly from TypeScript
npm run build      # Compile to dist/
npm test           # Run the test suite once
npm run test:watch # Run tests in watch mode
npm run check      # Build and test, matching CI

コマンドレジストリは、各 MCP ツールを src/tools の下に分離して保持します。プルリクエストを開く前に CONTRIBUTING.md を参照してください。

セキュリティ

このサーバーは認証情報をメモリ内で処理し、設定された BITBUCKET_URL にのみ送信します。サーバーを起動する前に、その URL を慎重に確認してください。書き込みツールを有効にすると、接続された MCP クライアントが認証済みの Bitbucket ユーザーとして PR コメントを投稿できるようになります。脆弱性を非公開で報告するには、SECURITY.md に従ってください。

ライセンス

MIT License の下で公開されています。

Available Tools

3 tools
add_pull_request_commentA

Creates a general, file, or inline line comment on a Bitbucket pull request. This is a write operation and requires BITBUCKET_ENABLE_WRITE_TOOLS=true.

NameRequiredDescriptionDefault
workspaceYesBitbucket Cloud workspace ID or Bitbucket Server/Data Center project key
repositoryYesRepository slug or repository name
pull_request_idYesPull request ID
commentYesComment text. Bitbucket Cloud renders supported Markdown.
file_pathNoOptional destination-side repository path for a file or line comment.
source_file_pathNoOptional previous path for a renamed or copied file. Used by Server/Data Center.
lineNoOptional 1-based diff line number. Requires file_path and line_type.
line_typeNoKind of diff line. Requires file_path and line.
line_sideNoDiff side. Defaults to old for removed lines and new otherwise.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description declares write operation and environment variable requirement, but omits details on side effects, permissions, rate limits, or comment management (editing/deletion).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: one sentence plus a note on prerequisites. No unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing explanation of return values (no output schema), no guidance on combining file_path, line, line_type, line_side for inline comments. Given 9 parameters and write nature, more context needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; each parameter is documented in the schema. The description adds no extra semantic value beyond summarizing the tool's purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it creates a comment on a Bitbucket pull request, specifying three types: general, file, or inline line comment. Different from sibling read-only tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly identifies it as a write operation requiring BITBUCKET_ENABLE_WRITE_TOOLS=true. Does not explicitly state when to use versus siblings, but the read-only nature of siblings implies the writing use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pull_requestA

Retrieves metadata, description, state/status, author, reviewers, source branch, destination branch, timestamps, and links for a specific Bitbucket pull request.

NameRequiredDescriptionDefault
workspaceYesBitbucket Cloud workspace ID or Bitbucket Server/Data Center project key
repositoryYesRepository slug or repository name
pull_request_idYesPull request ID

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes what data is retrieved but does not mention any behavioral traits such as authentication requirements, rate limits, or potential performance implications. For a simple read operation, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently lists the retrieved data without any fluff. Every phrase adds value, and the structure is front-loaded with the verb and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description does a good job of listing the expected return fields (metadata, description, state, author, reviewers, branches, timestamps, links). It is fairly comprehensive, though it could be improved by noting if any fields are nested or if there are pagination details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, meaning all parameters are described in the schema. The description adds no extra meaning beyond the schema; it simply restates that the tool retrieves for a specific pull request. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Retrieves' and clearly lists the resource ('metadata, description, state/status, author, reviewers, source branch, destination branch, timestamps, and links for a specific Bitbucket pull request'). It distinguishes from sibling tools (add_pull_request_comment and get_pull_request_diff) by focusing on retrieval of metadata, not adding comments or getting diffs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool vs alternatives. While the purpose is clear, there is no guidance on when not to use it or which sibling tool to choose for other tasks. The agent must rely on tool names and context, which is adequate but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pull_request_diffA

Retrieves the raw diff and, when available, a structured list of changed files for a specific Bitbucket pull request.

NameRequiredDescriptionDefault
workspaceYesBitbucket Cloud workspace ID or Bitbucket Server/Data Center project key
repositoryYesRepository slug or repository name
pull_request_idYesPull request ID

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description mentions return content (raw diff and structured files) but does not discuss side effects, authentication needs, or limitations such as file size constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that is direct and waste-free, conveying the essential information efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a retrieval tool with three fully described parameters and no output schema, the description adequately states what is returned. Slightly incomplete in not mentioning that diff may be large or truncated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all three parameters with descriptions (100% coverage). The tool description adds no extra meaning beyond the schema fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'retrieves' and resources 'raw diff' and 'structured list of changed files' for a specific Bitbucket pull request, distinguishing it from sibling tools like add_pull_request_comment and get_pull_request.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs siblings; usage is implied by the name and description but not directly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedadd_pull_request_comment
    • First observedget_pull_request
    • First observedget_pull_request_diff

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct aspect of pull requests: commenting, metadata retrieval, and diff retrieval. No functional overlap, making selection clear.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (add_*, get_*, get_*), which is predictable and easy to follow.

Tool Count3/5

Three tools is minimal for a Bitbucket server; it covers only basic pull request read operations and commenting, missing core CRUD operations, but it is not extreme.

Completeness2/5

The toolset lacks essential operations like listing, creating, updating, or merging pull requests. Agents cannot perform a full workflow, leaving significant gaps.

Related MCP Connectors

Related MCP Servers