# bitbucket-mcp

**English** · [Português (BR)](README.pt-BR.md)

MCP server for **Bitbucket Cloud**, focused on the *first pass* of pull-request review. **stdio** transport, for use with **Claude Code** or Claude Desktop.

## Why an API token (and not an app password)

Bitbucket Cloud app passwords have been in brownout since 2026-06-09 and are **removed on 2026-07-28**. This server uses an **API token**, and the HTTP Basic pair is `email:token` — the Bitbucket REST API requires the **Atlassian account email**, not the username. Using the username results in a silent `401`.

## 1. Create the API token

1. Bitbucket top bar → **Settings → Atlassian account settings → Security**.
2. **Create and manage API tokens → Create API token with scopes**.
3. Name it, set an expiry, and select **Bitbucket** as the app.
4. Minimum scopes for PR review:
   - `read:repository:bitbucket` (read repositories, diffs, files)
   - `read:pullrequest:bitbucket` (read PRs and comments)
   - `write:pullrequest:bitbucket` (comment, approve, request changes)
5. Copy the token (**shown only once**).

## 2. Install and build

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

This generates `dist/index.js` (the server binary).

## 3. Configure in Claude Code

Add this to the project's `.mcp.json` (or to your global Claude Code config):

```json
{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_EMAIL": "your-email@domain.com",
        "BITBUCKET_API_TOKEN": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}
```

Alternative, via the CLI:

```bash
claude mcp add bitbucket \
  -e BITBUCKET_EMAIL=your-email@domain.com \
  -e BITBUCKET_API_TOKEN=your_api_token \
  -e BITBUCKET_WORKSPACE=your_workspace \
  -- node /absolute/path/to/bitbucket-mcp/dist/index.js
```

`BITBUCKET_WORKSPACE` is optional; if omitted, each tool must be given `workspace` explicitly.

## Tools

Read (no side effects):

| Tool | Purpose |
|------|---------|
| `list_repositories` | Repositories in the workspace |
| `list_pull_requests` | PRs by state (OPEN/MERGED/DECLINED/SUPERSEDED) |
| `get_pull_request` | PR metadata (description, branches, reviewers, approvals) |
| `get_pull_request_diff` | Unified diff — the basis for the review |
| `get_pull_request_comments` | Existing comments (general and inline) |
| `get_pull_request_commits` | PR commits |
| `list_directory` | Lists the repo file tree at a commit/branch (explore the project) |
| `get_file` | Contents of a file (default branch if `commit` is omitted) |

Write (**mutate state in Bitbucket**):

| Tool | Purpose |
|------|---------|
| `add_pull_request_comment` | Comment on the PR; `path` + `line` together = inline |
| `approve_pull_request` | Approve the PR |
| `request_changes_pull_request` | Mark "request changes" |

## Security note

The token grants read/write access to the workspace's PRs. Treat it as a secret: keep it in an environment variable / secret manager, and never commit it. For a *first-pass* subagent that only suggests review without mutating anything, use a **read-only scoped** token — that way `approve`/`comment` fail on permission rather than relying on prompt discipline.

## License

[MIT](LICENSE) © José Danilo