Skip to main content
Glama
Sign In
deenesjakoruzh
Bitbucket MCP Server

Bitbucket MCP Server

by inceon
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Bitbucket MCP Server

License: MIT CI Node.js MCP

一个面向生产的 Model Context Protocol 服务器，用于从 Bitbucket Cloud 和 Bitbucket Server/Data Center 检索拉取请求元数据和差异，并支持可选开启的拉取请求评论。

Features

  • 支持 Bitbucket Cloud 和自托管的 Bitbucket Server/Data Center。

  • 提供聚焦于拉取请求元数据、差异、评审讨论以及一般或行内评论的工具。

  • 支持 bearer 令牌和基本认证。

  • 在 Bitbucket 提供时返回原始差异以及结构化的变更文件数据。

  • 通过可配置的 glob 模式排除生成的文件、文件夹或文件类型。

  • 在不破坏 UTF-8 字符的前提下限制大型差异。

  • 使用 stdio，且不会向 stdout 写入破坏协议的日志。

  • 默认保持评论创建功能禁用，并且不会批准、合并或以其他方式修改拉取请求。

Related MCP server: Atlassian Bitbucket MCP Server

Quick start

需要受支持的 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

在你的 MCP 客户端配置中设置 BITBUCKET_URL 和 BITBUCKET_TOKEN，然后使用 node dist/index.js 启动编译后的服务器。该服务器有意不自行加载 .env 文件；MCP 客户端应直接传递环境变量。

Authentication

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

仅授予凭证与你所启用工具所需的权限。创建评论需要创建拉取请求评论的权限。切勿提交凭证，也不要在问题报告中放置真实令牌。

Environment variables

Variable

Required

Default

Description

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

停止前从上游原始差异读取的最大字节数

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

设置为 true 以允许修改 Bitbucket 的工具，目前为 PR 评论创建

服务器仅将启动错误写入 stderr，并从 Bitbucket HTTP 错误片段中隐藏已配置的凭证。

MCP configuration

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"

Available tools

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，reason 为 max_comments 或 max_pages。

get_pull_request_commits

返回当前拉取请求中的提供方原生提交。使用它可将评审发现追溯到其来源提交，或验证后续工作是否解决了该问题。当达到配置的检索上限时，commitsStatus.complete 为 false，reason 为 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。对于 Cloud，rawDiffSource 为 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，reason 为 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 安全的评审前缀，不一定是完整的行、hunk 或可应用的补丁。

结构化文件页会一直跟踪，直到完成或达到配置的文件/页数上限，然后规范化为精简的评审元数据，而不是返回提供方的哈希、链接和重复的路径结构。只有 HTTP 404 之后才会报告不可用的 diffstat 或 changes 端点。授权、速率限制、服务器、响应格式错误、超时和传输故障会导致工具调用失败，而不会静默省略元数据。

Cloud 的 rawDiff 保留提供方的原始响应。Server/Data Center 使用结构化的 /diff 响应，并将其文件、hunk、段和行规范化为 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 一侧；显式设置 line_side 可将上下文评论放在 old 一侧。对于文件级评论，请提供 file_path 而不提供行字段。对于 Server/Data Center 上的重命名文件，source_file_path 可以标识先前的路径。

经过认证的 Bitbucket 用户将成为评论作者。在批准 MCP 客户端中的工具调用之前，请检查目标工作区、仓库、拉取请求 ID 和评论文本。

Provider behavior

URL 的主机名决定提供方。bitbucket.org 和 api.bitbucket.org 使用 Bitbucket Cloud；所有其他主机使用 Server/Data Center。

Cloud URL 规范化为一个 /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 之类的上下文路径，规范化为一个 /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 为权威来源。只有在验证了实时的 tools/list 模式和受控的 diff 响应之后，才应添加 Rovo 适配器；它必须保持显式配置，并且不能替代 Server/Data Center 支持。请参阅 Atlassian 的受支持工具页面。

路线图

未来版本计划涵盖以下领域：

  • 添加重试处理并改进速率限制诊断信息。

  • 提供规范化的拉取请求输出，同时保留对提供商特定字段的访问。

  • 添加用于列出拉取请求和获取构建状态的只读工具。

  • 提供可选的 Streamable HTTP 传输，同时保持 stdio 为默认方式。

  • 发布带版本号的版本，提供更简单的安装和升级路径。

写入操作默认保持禁用。批准、合并以及其他高影响的 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
Deploy Server
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

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.

Maintenance

ActivityStale
ResponsivenessOutdated data

Resources

Related MCP Connectors

Related MCP Servers