# bitbucket-mcp

A small local [MCP](https://modelcontextprotocol.io) server wrapping the
Bitbucket Cloud API for pull-request reviews in Claude Code. Works with any
workspace/repo via env vars; the workspace defaults to `campsys`, and you set
`BB_REPO` per repo you review.

## Tools

| Tool | Type | Purpose |
|------|------|---------|
| `get_pr` | read | PR metadata (title, state, branches, commit hashes) |
| `list_comments` | read | All comments (paginated), inline path/line, reply parent ids |
| `get_diff` | read | PR diff via local `git diff base...head` (avoids the API `/diff` 401) |
| `post_comment` | **write** | Post a comment; supports inline (`path`+`to`) and replies (`parent_id`) |
| `approve` | **write** | Approve the PR |

## Requirements

- **Node 18+** (uses built-in `fetch`; developed on Node 25).
- **git** on `PATH` (used by `get_diff`).
- A **scoped Atlassian API token** — see below. The token is per-person and is
  never committed or shared.

## 1. Get your own Atlassian API token

App Passwords are being removed by Atlassian (final removal 2026-07-28), so use a
**scoped API token**:

1. Create one at <https://id.atlassian.com/manage-profile/security/api-tokens>.
2. Give it these Bitbucket scopes:
   `read:pullrequest:bitbucket`, `write:pullrequest:bitbucket`,
   `read:repository:bitbucket`, `read:account`.
   (A plain Jira token without Bitbucket scopes returns 401.)

Set these environment variables (persist them for your user/shell):

| Var | Value |
|-----|-------|
| `BB_EMAIL` | your Atlassian account email |
| `BB_API_TOKEN` | the scoped token from step 1 |

**Windows (PowerShell, persistent):**
```powershell
[Environment]::SetEnvironmentVariable('BB_EMAIL','you@company.com','User')
[Environment]::SetEnvironmentVariable('BB_API_TOKEN','<token>','User')
```
**macOS/Linux:** add `export BB_EMAIL=...` / `export BB_API_TOKEN=...` to your
shell profile.

## 2. Clone and install

```sh
git clone <REPO_URL> bitbucket-mcp
cd bitbucket-mcp
npm install
```

## 3. Register with Claude Code

**Option A — user scope (recommended; available in every project):**
```sh
claude mcp add bitbucket --scope user -- node /absolute/path/to/bitbucket-mcp/server.js
```
The server inherits `BB_EMAIL`/`BB_API_TOKEN` from your environment.

**Option B — a single project:** copy the `bitbucket` block from
[`mcp-config.example.json`](mcp-config.example.json) into that project's
`.mcp.json`, replacing the path. (Add `.mcp.json` to that repo's `.gitignore` if
you don't want it committed.)

Restart Claude Code; approve the `bitbucket` server when prompted.

## Configuration (env)

| Var | Default | Notes |
|-----|---------|-------|
| `BB_EMAIL` | — | required |
| `BB_API_TOKEN` | — | required |
| `BB_REPO` | — | required; repo slug being reviewed |
| `BB_WORKSPACE` | `campsys` | Bitbucket workspace |
| `BB_REPO_PATH` | current working dir | local checkout used by `get_diff` |

`get_diff` fetches the PR source branch into `refs/remotes/origin/bb-mcp-tmp`
and diffs three-dot against the PR's `destination.commit.hash`. It runs git in
`BB_REPO_PATH`, so that must be a local clone of the repo being reviewed.

## Smoke test

```sh
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node server.js
```
Should list the five tools.

## Note on write tools

`post_comment` and `approve` mutate the PR. The intended workflow is to draft
content, get explicit human approval, then call the write tool — not to post
automatically.