# BitBucket-MCP-To-Review-PRs

A read-only MCP (Model Context Protocol) server for the Bitbucket Cloud REST API v2.0. Enables AI assistants (Kiro, VS Code, Claude Desktop, etc.) to browse workspaces, repositories, and review pull requests — all without modifying anything in Bitbucket.

## Features

- List workspaces and repositories
- List, view, and review pull requests
- Get PR diffs, diffstats, comments, and commits
- Parse Bitbucket PR URLs for one-shot review context
- View file contents at any commit
- Automatic pagination and rate limit handling
- Strictly read-only (GET requests only)

## Prerequisites

- [Bun](https://bun.sh/) runtime
- A Bitbucket Cloud account with an [App Password](https://bitbucket.org/account/settings/app-passwords/)

### App Password Scopes

Create an App Password with these read permissions:

- Account (Read)
- Workspace membership (Read)
- Repositories (Read)
- Pull requests (Read)

## Setup

```bash
git clone https://github.com/arslanismail/BitBucket-MCP-To-Review-PRs.git
cd BitBucket-MCP-To-Review-PRs
bun install
```

## MCP Client Configuration

Add this to your MCP client config:

**Kiro:** `.kiro/settings/mcp.json`
**VS Code (Copilot):** `.vscode/mcp.json`
**Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "bitbucket": {
      "command": "bun",
      "args": ["run", "src/index.ts"],
      "cwd": "/absolute/path/to/BitBucket-MCP-To-Review-PRs",
      "env": {
        "BITBUCKET_USERNAME": "<your-atlassian-email>",
        "BITBUCKET_TOKEN": "<your-app-password>"
      }
    }
  }
}
```

> **Important:** Use your Atlassian account email as the username, not your Bitbucket username.

## Available Tools

| Tool | Description | Input |
|------|-------------|-------|
| `list_workspaces` | List all accessible workspaces | — |
| `list_repositories` | List repos in a workspace | `workspace` |
| `list_pull_requests` | List PRs (defaults to OPEN) | `workspace`, `repo_slug`, `state?` |
| `get_pull_request` | Get full PR details | `workspace`, `repo_slug`, `pull_request_id` |
| `get_pull_request_diff` | Get unified diff | `workspace`, `repo_slug`, `pull_request_id` |
| `get_pull_request_diffstat` | Get files changed summary | `workspace`, `repo_slug`, `pull_request_id` |
| `get_pull_request_comments` | Get all PR comments | `workspace`, `repo_slug`, `pull_request_id` |
| `get_pull_request_commits` | Get commits in a PR | `workspace`, `repo_slug`, `pull_request_id` |
| `get_pr_from_link` | Parse PR URL, return details + diff + diffstat | `url` |
| `get_file_contents` | Get file at a specific commit | `workspace`, `repo_slug`, `commit`, `path` |

## Example Usage

Once connected, ask your AI assistant:

- "List my Bitbucket workspaces"
- "Show me open PRs in avizia/one"
- "Review this PR: https://bitbucket.org/myworkspace/myrepo/pull-requests/123"

## Project Structure

```
src/
├── index.ts              # Entry point, env validation, tool registration
├── bitbucket-client.ts   # HTTP client (GET-only, auth, pagination, rate limiting)
├── types.ts              # Bitbucket API response interfaces
└── tools/                # Individual tool implementations
    ├── list-workspaces.ts
    ├── list-repositories.ts
    ├── list-pull-requests.ts
    ├── get-pull-request.ts
    ├── get-pull-request-diff.ts
    ├── get-pull-request-diffstat.ts
    ├── get-pull-request-comments.ts
    ├── get-pull-request-commits.ts
    ├── get-pr-from-link.ts
    └── get-file-contents.ts
```

## License

MIT