Purpose
bitbucket-mcp is an MCP (Model Context Protocol) server for Bitbucket Cloud, focused on the initial process of pull request review. It uses stdio transport and can be used with Claude Code or Claude Desktop.
Main capabilities
The server provides two sets of tools: read and write.
Read (no side effects)
- Read PRs
- Read diffs
- Read comments
- Read commits
- Read files
Write (modifies Bitbucket state)
- Post inline comments or regular comments
- Approve
- Request changes
Usage
1. Create an API token
Bitbucket Cloud app passwords enter their deprecation period starting 2026-06-09 and will be removed on 2026-07-28. Therefore this server uses API tokens; the HTTP Basic authentication pair is email:token—the Bitbucket REST API requires the Atlassian account email, not the username. Using a username results in a silent 401 error.
Creation steps:
- Go to the Bitbucket top bar → Settings → Atlassian account settings → Security.
- Select Create and manage API tokens → Create API token with scopes.
- Name it, set an expiration time, and select Bitbucket as the application.
- Select the minimum scopes required for PR review:
- read:repository:bitbucket (read repositories, diffs, files)
- read:pullrequest:bitbucket (read PRs and comments)
- write:pullrequest:bitbucket (comments, approvals, request changes)
- Copy the token (it is shown only once).
2. Installation and build
After installation and build, dist/index.js (the server binary) is generated. The specific installation commands are currently not provided in the material.
3. Configure in Claude Code
Add the configuration to the project's .mcp.json (or the global Claude Code configuration). It can also be configured via the CLI. The specific configuration example is currently not provided in the material.
The environment variable BITBUCKET_WORKSPACE is optional; if omitted, each tool must explicitly specify the workspace.
Applicable scenarios
Suitable for scenarios that require automated or assisted Bitbucket Cloud pull request review, especially as a sub-agent for a "first-pass" review that only suggests reviews without actually modifying anything. It is also suitable for automated workflows that need to read PR-related information and post comments, approvals, or request changes.
Limitations and security recommendations
The token grants read and write access to workspace PRs and should be treated as confidential: store it in environment variables or a secrets manager, and never commit it to a code repository. If you want the sub-agent to only suggest reviews without modifying anything, it is recommended to use a read-only scope token, so that approve/comment operations fail due to insufficient permissions rather than relying on prompt constraints.
License
MIT © José Danilo
