# Bitbucket MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/inceon/bitbucket-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/inceon/bitbucket-mcp/actions/workflows/ci.yml)
![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933)
![MCP](https://img.shields.io/badge/Model_Context_Protocol-stdio-5A45FF)

A production-focused [Model Context Protocol](https://modelcontextprotocol.io/) 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.

## Quick start

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

```bash
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:

```bash
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:

```bash
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 | `200000` | Maximum UTF-8 byte size returned in `rawDiff`; increase explicitly for unusually large-context clients |
| `BITBUCKET_MAX_DIFF_INPUT_BYTES` | No | `10000000` | Maximum bytes read from an upstream raw diff before stopping |
| `BITBUCKET_MAX_JSON_BYTES` | No | `10000000` | Maximum bytes read from any Bitbucket JSON response |
| `BITBUCKET_MAX_COMMENT_COUNT` | No | `5000` | Maximum pull request comments collected across pages |
| `BITBUCKET_MAX_COMMENT_PAGES` | No | `100` | Maximum pull request comment pages followed |
| `BITBUCKET_MAX_COMMIT_COUNT` | No | `5000` | Maximum pull request commits collected across pages |
| `BITBUCKET_MAX_COMMIT_PAGES` | No | `100` | Maximum pull request commit pages followed |
| `BITBUCKET_MAX_DIFF_FILES` | No | `5000` | Maximum structured changed-file entries collected across pages |
| `BITBUCKET_MAX_DIFF_PAGES` | No | `100` | Maximum structured changed-file pages followed |
| `BITBUCKET_REQUEST_TIMEOUT_MS` | No | `30000` | Deadline in milliseconds for each Bitbucket HTTP request |
| `BITBUCKET_IGNORE_PATTERNS` | No | - | Comma-separated file globs excluded from every PR diff |
| `BITBUCKET_ENABLE_WRITE_TOOLS` | No | `false` | Set to `true` to allow tools that modify Bitbucket: PR creation and comments |

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

## MCP configuration

Claude Desktop configuration:

```json
{
  "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:

```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`

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

```json
{
  "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.

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/supported-tools/#read).

## 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](https://github.com/inceon/bitbucket-mcp/issues).

## Development

```bash
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](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](SECURITY.md).

## License

Released under the [MIT License](LICENSE).