# bitbucket-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for
**Bitbucket Cloud**. Review, manage, and merge pull requests, assign reviewers
_by name_, read files at a ref, and inspect pipeline status — from any MCP
client (Claude Desktop, Cursor, Claude Code) or a hosted HTTP endpoint.

It talks to the [Bitbucket Cloud REST API v2.0](https://developer.atlassian.com/cloud/bitbucket/rest/)
with a single access token. All read paths are paginated and capped; write
tools (create/merge PR, comments, reviewers) are explicit.

## Tools

All tools are prefixed `bb_`.

| Tool | What it does |
| --- | --- |
| `bb_list_pull_requests` | List PRs in a repo, filtered by state |
| `bb_get_pull_request` | Full detail for one PR |
| `bb_get_pull_request_diff` | Unified diff for a PR |
| `bb_get_pull_request_comments` | All comments on a PR (inline + general) |
| `bb_get_pull_request_status` | Aggregated build/status checks for a PR |
| `bb_get_pipeline_status` | Commit statuses for an arbitrary ref |
| `bb_create_pull_request` | Open a PR (optionally with reviewers) |
| `bb_merge_pull_request` | Merge a PR (merge_commit / squash / fast_forward) |
| `bb_create_pull_request_comment` | Add a comment (optionally inline on a file/line) |
| `bb_edit_pull_request_comment` | Edit one of your comments |
| `bb_delete_pull_request_comment` | Delete one of your comments |
| `bb_add_pull_request_reviewers` | Assign reviewers **by name** or UUID |
| `bb_list_workspace_members` | Inspect the local known-members directory |
| `bb_get_file` | Read a file's contents at a branch/commit |

### Assigning reviewers by name

Bitbucket's `/workspaces/{workspace}/members` endpoint requires the `account`
scope (which PR tokens don't carry), so you can't resolve a person's name to
their account UUID over the API. This server keeps a small **local directory**
of known members so `bb_add_pull_request_reviewers` accepts a plain name (e.g.
`"Jane Doe"`) and resolves it offline. Raw account UUIDs always work too.

Seed people in either place (both use the same JSON shape; the env var merges on
top of the file):

- `tools/bitbucket/directory.json` — copy [`directory.example.json`](tools/bitbucket/directory.example.json) and fill it in. **This file is git-ignored** so real account UUIDs never get committed.
- `BITBUCKET_KNOWN_MEMBERS` env var — handy for hosted deploys.

```json
{
  "your-workspace-slug": [
    { "uuid": "{00000000-0000-0000-0000-000000000000}", "display_name": "Jane Doe", "nickname": "Jane" }
  ]
}
```

## Configuration

Set via environment variables (see [`.env.example`](.env.example)). Prefix `BITBUCKET_`.

| Variable | Required | Description |
| --- | --- | --- |
| `BITBUCKET_API_KEY` | ✅ | Access token (Bearer) or app password |
| `BITBUCKET_USERNAME` | — | Set **only** when using an app password (switches to Basic auth) |
| `BITBUCKET_WORKSPACE` | — | Default workspace slug, so tools don't need it each call |
| `BITBUCKET_DEFAULT_REPO` | — | Default repo slug |
| `BITBUCKET_KNOWN_MEMBERS` | — | JSON of extra known members (merged over `directory.json`) |
| `BITBUCKET_MAX_PAGES` | — | Pagination cap (default `10`) |
| `BITBUCKET_TIMEOUT` | — | HTTP timeout in seconds (default `30`) |

Tools are always listed but return a clear "not configured" error if
`BITBUCKET_API_KEY` is missing, so the server starts cleanly without secrets.

## Quick start (local, stdio)

Requires Python 3.11+.

```bash
git clone https://github.com/matt-nann/bitbucket-mcp.git
cd bitbucket-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export BITBUCKET_API_KEY=your-token
python server.py            # stdio (default)
```

### Wire it into an MCP client

**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "bitbucket": {
      "command": "python",
      "args": ["/absolute/path/to/bitbucket-mcp/server.py"],
      "env": {
        "BITBUCKET_API_KEY": "your-token",
        "BITBUCKET_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add bitbucket \
  --env BITBUCKET_API_KEY=your-token \
  --env BITBUCKET_WORKSPACE=your-workspace-slug \
  -- python /absolute/path/to/bitbucket-mcp/server.py
```

## Hosting (HTTP)

The same server runs over streamable HTTP for a shared/hosted deployment. It
binds **dual-stack IPv6** and honors `$PORT`, so it works on Railway (and
Fly/Heroku/Docker) out of the box:

```bash
MCP_TRANSPORT=http PORT=8000 python server.py --http
# MCP endpoint: http://localhost:8000/mcp   health: /health
```

⚠️ **HTTP mode has no built-in authentication** and every request uses the one
`BITBUCKET_API_KEY` identity. Don't expose it publicly without an auth proxy in
front. See **[HOSTING.md](HOSTING.md)** for the full Railway walkthrough,
Docker instructions, and the security model.

## Provenance

Extracted from a larger internal multi-tool MCP server into a standalone,
self-contained package. No internal identifiers or shared auth layers are
included; the member directory ships only as a placeholder example.

## License

[MIT](LICENSE)