bitbucket-mcp
# bitbucket-mcp
> ⚠️ This is a personal project built for fun and carries no support or
> guarantees. For anything that matters, prefer the official Atlassian MCP
> server.
An MCP server for Bitbucket Cloud, covering pull requests, pull request
comments, and pipelines. Distributed as a Claude Code plugin.
## Setup
Requires [`uv`](https://docs.astral.sh/uv/) on `PATH`.
**1. Install**
```sh
claude plugin marketplace add Zomino/bitbucket-mcp
claude plugin install bitbucket@bitbucket
```
**2. Create a token**
Create a Bitbucket API token at
https://id.atlassian.com/manage-profile/security/api-tokens. Grant exactly
these scopes:
| Scope | Why |
| --- | --- |
| `read:pullrequest:bitbucket` | List and read pull requests, diffs, commits, statuses, and comments |
| `write:pullrequest:bitbucket` | Create, update, comment, approve, request changes, decline, and merge |
| `read:pipeline:bitbucket` | Read pipelines, steps, and step logs |
| `read:repository:bitbucket` | Read the repository content behind pull request diffs and commits |
With `BITBUCKET_READ_ONLY=true`, drop `write:pullrequest:bitbucket` and grant
only the three `read:` scopes.
**3. Set the env vars**
Set these in the `env` block of a Claude Code settings file
(`~/.claude/settings.json` for every project, or `.claude/settings.json` for
one), then restart the session.
```json
{
"env": {
"BITBUCKET_WORKSPACE": "my-workspace",
"BITBUCKET_REPO": "my-repo",
"BITBUCKET_USERNAME": "me@example.com",
"BITBUCKET_API_TOKEN": "…"
}
}
```
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `BITBUCKET_WORKSPACE` | yes | | Workspace slug |
| `BITBUCKET_REPO` | yes | | Repository slug |
| `BITBUCKET_USERNAME` | yes | | Atlassian account email |
| `BITBUCKET_API_TOKEN` | yes | | Token from step 2 |
| `BITBUCKET_READ_ONLY` | no | `false` | Expose read-only tools only |
| `BITBUCKET_ENABLE_PULL_REQUESTS` | no | `true` | Toggle pull request tools |
| `BITBUCKET_ENABLE_PIPELINES` | no | `true` | Toggle pipeline tools |
## Development
- Run the test suite with `uv run pytest`.
- Build a wheel with `uv build`.
- Publish with `uv publish`.
One server instance targets one workspace and repository, selected by the env
vars above.
TDQS
Scored across 26 tools
Each tool targets a distinct resource and action. Pull request tools are clearly separated by operation (get, create, update, merge, approve, etc.) and by scope (list vs detail, comments vs inline comments vs replies). Pipeline tools are similarly distinct for runs, steps, and logs.
Tool names consistently follow a verb_noun pattern (e.g., get_pull_request, create_pull_request_comment, get_pipeline_steps). Even the slightly longer names like request_pull_request_changes or diagnose_pipeline_failure remain readable and align with the pattern.
26 tools is slightly above the typical 3-15 range, but the scope intentionally covers both pull request management (21 tools) and pipeline inspection (5 tools). Each tool serves a distinct, non-redundant purpose, making the count justified rather than bloated.
The pull request lifecycle is well covered: create, update, merge, decline, approve, request changes, comments, diffs, commits, and statuses. Pipelines cover listing, getting details, steps, logs, and failure diagnosis. Minor gaps exist (e.g., no general list of PRs filtered by state, no pipeline triggering), but they are non-critical for most workflows.