Bitbucket MCP Server

A production-focused Model Context Protocol server for retrieving pull request metadata and diffs from Bitbucket Cloud and Bitbucket Server/Data Center, with opt-in pull request comments.

Features

• Supports Bitbucket Cloud and self-hosted Bitbucket Server/Data Center.

• Exposes focused tools for pull request metadata, diffs, review discussion, and general or inline comments.

• Supports bearer tokens and basic authentication.

• Returns raw diffs plus structured changed-file data when Bitbucket provides it.

• Excludes generated files, folders, or file types through configurable glob patterns.

• Caps large diffs without breaking UTF-8 characters.

• Uses stdio without writing protocol-breaking logs to stdout.

• Keeps comment creation disabled by default and does not approve, merge, or otherwise modify pull requests.

Related MCP server: Atlassian Bitbucket MCP Server

Quick start

Requires a supported Node.js LTS release (Node.js 22 or newer).

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

Set BITBUCKET_URL and BITBUCKET_TOKEN in your MCP client configuration, then launch the compiled server with node dist/index.js. The server intentionally does not load .env files itself; MCP clients should pass environment variables directly.

Authentication

Bearer authentication is the default and is recommended for Bitbucket Server/Data Center personal access tokens:

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

For Bitbucket Cloud API tokens or app passwords that require basic authentication:

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

Grant the credential only the permissions needed for the tools you enable. Comment creation requires permission to create pull request comments. Never commit credentials or put real tokens in issue reports.

Environment variables

The server writes startup errors only to stderr and redacts configured credentials from Bitbucket HTTP error snippets.

MCP configuration

Claude Desktop configuration:

{
  "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 configuration:

[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

Returns pull request metadata, including its description, state, author, reviewers, branches, timestamps, and links.

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

get_pull_request_comments

Returns existing general and inline discussion as provider-native comment objects. Use it before posting a review finding to account for existing feedback. commentsStatus.complete is false with reason max_comments or max_pages when the configured retrieval bounds are reached.

get_pull_request_commits

Returns provider-native commits currently in the pull request. Use it to trace a finding to its originating commit or verify whether later work addresses it. commitsStatus.complete is false with reason max_commits or max_pages when the configured retrieval bounds are reached.

get_pull_request_diff

Returns a git-style review diff and structured changed files when available.

{
  "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
  }
}

Diff output is available both as backward-compatible JSON text and as MCP structuredContent, with an advertised output schema. It includes:

• provider, pull_request_id, rawDiff, rawDiffBytes, and rawDiffSource. rawDiffSource is provider_raw for Cloud or server_structured for a locally normalized Server/Data Center response.

• truncated plus truncationReason: input_limit when the upstream Cloud read limit was reached, output_limit when the filtered result exceeded BITBUCKET_MAX_DIFF_BYTES, or provider_limit when Server/Data Center marked its structured diff as truncated.

• Optional compact files entries contain only path, normalized status, and oldPath for renames or copies. Required filesStatus reports completeness; complete is false with reason max_files, max_pages, or unsupported, and returned reflects the filtered entries actually returned.

• Optional ignored metadata when exclusions are active.

Complete result:

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

Bounded partial result:

{
  "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"
}

Truncated rawDiff is a UTF-8-safe review prefix, not necessarily a complete line, hunk, or applicable patch.

Structured file pages are followed until complete or until a configured files/pages bound is reached, then normalized to compact review metadata rather than returning provider hashes, links, and duplicate path structures. An unavailable diffstat or changes endpoint is reported only after HTTP 404. Authorization, rate-limit, server, malformed-response, timeout, and transport failures fail the tool call rather than silently omitting metadata.

Cloud rawDiff preserves the provider's raw response. Server/Data Center uses the structured /diff response and normalizes its files, hunks, segments, and lines into git-style review text; this avoids version-specific failures from the separate .diff export route. rawDiffSource makes that distinction explicit.

path is supported for both providers and is the preferred way to review large pull requests file-by-file; returned files metadata is scoped to the same path. renames is Cloud-only. context maps to Cloud context and Server/Data Center contextLines. ignore_whitespace maps to Cloud ignore_whitespace and Server/Data Center whitespace=ignore-all. When absent, these controls do not alter provider defaults.

Patterns use repository-relative paths and support *, **, and ?. A pattern without /, such as package-lock.json or *.png, matches that filename anywhere. A trailing slash excludes a directory recursively. When exclusions are active, the response includes ignored.patterns, ignored.files, and ignored.rawDiffFiltered. A false rawDiffFiltered value means a Cloud provider returned a non-git diff format that could not be filtered safely; the response is preserved instead of silently dropping content.

add_pull_request_comment

Creates a general, file-level, or inline line comment on a pull request. This write operation is available only when BITBUCKET_ENABLE_WRITE_TOOLS=true is set in the MCP server environment.

General comment:

{
  "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."
  }
}

Inline comment on an added line:

{
  "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"
  }
}

Use line_type values added, removed, or context. Added lines default to the new side, removed lines default to the old side, and context lines default to new; set line_side explicitly to place a context comment on old. Provide file_path without line fields for a file-level comment. For renamed files on Server/Data Center, source_file_path can identify the previous path.

The authenticated Bitbucket user becomes the comment author. Review the target workspace, repository, pull request ID, and comment text before approving the tool call in your MCP client.

create_pull_request

Creates a pull request from a pushed source_branch into destination_branch. This write operation requires BITBUCKET_ENABLE_WRITE_TOOLS=true. Supply a title and verify the workspace, repository, and target branch before approval; the authenticated Bitbucket user becomes the author.

Provider behavior

The URL host determines the provider. bitbucket.org and api.bitbucket.org use Bitbucket Cloud; all other hosts use Server/Data Center.

Cloud URLs are normalized to one /2.0 API prefix and use:

• /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 when enabled)

• /repositories/{workspace}/{repository}/pullrequests (POST when enabled)

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

Server/Data Center URLs preserve a context path such as /bitbucket, normalize to one /rest/api/1.0 prefix, and use:

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

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff (structured diff normalized to git-style review text)

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff/{path} (path-scoped structured diff)

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

• /projects/{project}/repos/{repository}/pull-requests/{id}/comments (GET; POST when enabled)

• /projects/{project}/repos/{repository}/pull-requests (POST when enabled)

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

The optional diffstat or changes request reports filesStatus.reason: "unsupported" after HTTP 404. Other HTTP, timeout, transport, and parsing failures fail the tool call so incomplete metadata is not mistaken for a complete response.

Atlassian Rovo MCP

Atlassian documents a Cloud-only bitbucketPullRequest.diff action, but does not publish its argument schema, output shape, pagination, filtering, or truncation contract. This server therefore keeps direct Bitbucket APIs authoritative. A Rovo adapter should be added only after validating a live tools/list schema and controlled diff response; it must remain explicitly configured and cannot replace Server/Data Center support. See Atlassian's supported-tools page.

Roadmap

Planned areas for future releases include:

• Add retry handling and clearer rate-limit diagnostics.

• Provide normalized pull request output while retaining access to provider-specific fields.

• Add read-only tools for listing pull requests and retrieving build status.

• Offer an optional Streamable HTTP transport while keeping stdio as the default.

• Publish versioned releases with simpler installation and upgrade paths.

Write operations will remain disabled by default. Approving, merging, and other high-impact Bitbucket operations are not planned. Ideas and implementation proposals are welcome through GitHub issues.

Development

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

The command registry keeps each MCP tool isolated under src/tools. See CONTRIBUTING.md before opening a pull request.

Security

This server handles credentials in memory and sends them only to the configured BITBUCKET_URL. Review that URL carefully before starting the server. Enabling write tools allows connected MCP clients to create pull requests and publish PR comments as the authenticated Bitbucket user. To report a vulnerability privately, follow SECURITY.md.

License

Released under the MIT License.