# bb-mcp-server

An [MCP](https://modelcontextprotocol.io) server for [Bitbucket Cloud](https://bitbucket.org), giving
MCP clients (Claude Code, Claude Desktop, etc.) tools to read and manage **pull requests, their
comments, and their descriptions**.

Atlassian has [announced](https://support.atlassian.com/bitbucket-cloud/docs/interacting-with-bitbucket-via-mcp/)
an official Bitbucket MCP server; at the time this was written it wasn't yet available, so this
fills the gap with the same underlying REST API.

## Features

- **Pull requests** — list, get, create, update, merge, decline, approve/unapprove, diff, diffstat
- **Comments** — list, get, create (general, inline, or as a reply), update, delete
- **Descriptions** — focused get/update tools that touch only the description field

See [Tools](#tools) below for the full list.

## Requirements

- Node.js >= 18.17
- A Bitbucket Cloud account with an [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens)

## Setup

```bash
npm install
npm run build
```

Configure credentials via environment variables (see [.env.example](.env.example)):

| Variable              | Required | Description                                                         |
| --------------------- | -------- | ------------------------------------------------------------------- |
| `BITBUCKET_EMAIL`     | yes      | Atlassian account email, used with the API token for Basic Auth.    |
| `BITBUCKET_API_TOKEN` | yes      | API token from id.atlassian.com.                                    |
| `BITBUCKET_WORKSPACE` | no       | Default workspace slug, so tools can omit `workspace` per call.     |
| `BITBUCKET_REPO_SLUG` | no       | Default repository slug, so tools can omit `repoSlug` per call.     |
| `BITBUCKET_BASE_URL`  | no       | API base URL override. Defaults to `https://api.bitbucket.org/2.0`. |

### Register with an MCP client

Example for Claude Code (`claude mcp add`) or a client's `mcp.json`:

```json
{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bb-mcp-server/dist/index.js"],
      "env": {
        "BITBUCKET_EMAIL": "you@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "my-workspace",
        "BITBUCKET_REPO_SLUG": "my-repo"
      }
    }
  }
}
```

`BITBUCKET_WORKSPACE` and `BITBUCKET_REPO_SLUG` are optional — omit them to require every tool
call to specify `workspace`/`repoSlug` explicitly, which is useful if the client should be able to
work across multiple repositories.

### Try it with the MCP Inspector

```bash
npm run inspector
```

## Tools

All tools accept optional `workspace` / `repoSlug` arguments that fall back to
`BITBUCKET_WORKSPACE` / `BITBUCKET_REPO_SLUG` when omitted.

### Pull requests

| Tool                           | Description                                                |
| ------------------------------ | ---------------------------------------------------------- |
| `bb_list_pull_requests`        | List PRs, filterable by state or a Bitbucket query string. |
| `bb_get_pull_request`          | Fetch full details of one PR.                              |
| `bb_create_pull_request`       | Open a new PR.                                             |
| `bb_update_pull_request`       | Update title, description, reviewers, and/or destination.  |
| `bb_merge_pull_request`        | Merge an open PR.                                          |
| `bb_decline_pull_request`      | Decline an open PR.                                        |
| `bb_approve_pull_request`      | Approve a PR as the authenticated user.                    |
| `bb_unapprove_pull_request`    | Remove the authenticated user's approval.                  |
| `bb_get_pull_request_diff`     | Fetch the unified diff as raw text.                        |
| `bb_get_pull_request_diffstat` | Fetch a per-file change summary.                           |

### Comments

| Tool                             | Description                                                                                   |
| -------------------------------- | --------------------------------------------------------------------------------------------- |
| `bb_list_pull_request_comments`  | List all (non-deleted) comments on a PR.                                                      |
| `bb_get_pull_request_comment`    | Fetch a single comment.                                                                       |
| `bb_create_pull_request_comment` | Add a comment — general, inline (via `inlinePath`/`inlineLine`), or a reply (via `parentId`). |
| `bb_update_pull_request_comment` | Edit a comment's body.                                                                        |
| `bb_delete_pull_request_comment` | Delete a comment.                                                                             |

### Descriptions

| Tool                                 | Description                                                     |
| ------------------------------------ | --------------------------------------------------------------- |
| `bb_get_pull_request_description`    | Read just a PR's description.                                   |
| `bb_update_pull_request_description` | Replace just a PR's description, without touching other fields. |

## Development

```bash
npm run dev         # run the server directly with tsx (no build step)
npm run typecheck   # tsc --noEmit
npm run lint         # eslint
npm run format       # prettier --write
npm test             # vitest
npm run build         # compile to dist/
```

### Architecture

```
src/
  config.ts           # env var loading/validation (zod)
  bitbucket/
    client.ts          # typed Bitbucket REST API v2.0 client (auth, pagination, errors)
    errors.ts           # BitbucketApiError
    types.ts             # Bitbucket API response shapes
  tools/
    shared.ts            # zod param helpers, workspace/repo resolution, error wrapping
    pullRequests.ts        # bb_* PR tools
    comments.ts              # bb_* comment tools
    descriptions.ts           # bb_* description tools
    index.ts                   # registerAllTools
  server.ts                     # builds the McpServer and registers tools
  index.ts                       # stdio entrypoint
```

## Authentication notes

This server authenticates with HTTP Basic Auth using your Atlassian account email and an
[API token](https://id.atlassian.com/manage-profile/security/api-tokens) — the auth method
Atlassian currently recommends for Bitbucket Cloud (app passwords are being phased out). The
token only needs the Pull Requests scope for the operations this server performs.

## License

MIT