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, and general or inline comments.
• Supports bearer tokens and basic authentication.
• Returns raw diffs plus structured changed-file data when Bitbucket provides it.
• 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.

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

Variable	Required	Default	Description
BITBUCKET_URL	Yes	-	Bitbucket base URL, such as https://api.bitbucket.org or https://bitbucket.example.com/bitbucket
BITBUCKET_TOKEN	Yes	-	API token, app password, or personal access token
BITBUCKET_AUTH_TYPE	No	bearer	bearer or basic
BITBUCKET_USERNAME	For basic auth	-	Username paired with the token for basic auth
BITBUCKET_MAX_DIFF_BYTES	No	1000000	Maximum UTF-8 byte size returned in rawDiff
BITBUCKET_ENABLE_WRITE_TOOLS	No	false	Set to true to allow tools that modify Bitbucket, currently PR comment creation

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_diff

Returns the raw diff and structured changed files when available.

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

Diff output includes provider, pull_request_id, rawDiff, optional files, and truncated. Truncation respects UTF-8 character boundaries.

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.

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 (POST, when enabled)

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
• /projects/{project}/repos/{repository}/pull-requests/{id}/changes
• /projects/{project}/repos/{repository}/pull-requests/{id}/comments (POST, when enabled)

The optional diffstat or changes request is omitted from the result when the Bitbucket instance does not provide it.

Roadmap

Planned areas for future releases include:

• [ ] Follow pagination for complete Cloud diffstat and Server/Data Center changes results.
• [ ] Add request timeouts, 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 commits, comments, and 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 publish PR comments as the authenticated Bitbucket user. To report a vulnerability privately, follow SECURITY.md.

License

Released under the MIT License.