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 on PATH.

1. Install

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.

{
  "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.