Bitbucket MCP Server
A FastMCP server for managing Pull Requests on Bitbucket Cloud. Create, list, view, update, and review PRs directly from Claude.
Features
- Create PRs with automatic default reviewer support
- List and view PR details
- Update PR title, description, destination branch, and reviewers
- Approve, unapprove, or request changes on PRs
- Add comments to PRs
- List workspace members for reviewer selection
Installation
git clone https://github.com/Acendas/bitbucket-mcp.git
cd bitbucket-mcp
pip install -r requirements.txt
Or with uv:
git clone https://github.com/Acendas/bitbucket-mcp.git
cd bitbucket-mcp
uv pip install -r requirements.txt
Getting an API Token
- Go to Atlassian API Tokens
- Click Create API token
- Give it a name (e.g., "Bitbucket MCP")
- Copy the generated token
Configuration
Option 1: Interactive Setup (Recommended)
Use the setup_bitbucket tool:
setup_bitbucket(
workspace="your-workspace",
username="your-email@example.com",
api_token="your-api-token"
)
This stores credentials securely in ~/.bitbucket-mcp/config.json with 600 permissions.
Option 2: Environment Variables
export BITBUCKET_API_TOKEN="your-api-token"
export BITBUCKET_USERNAME="your-email@example.com"
export BITBUCKET_WORKSPACE="your-workspace" # optional default
Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"bitbucket": {
"command": "python",
"args": ["/path/to/bitbucket-mcp/server.py"]
}
}
}
Or with uv:
{
"mcpServers": {
"bitbucket": {
"command": "uv",
"args": ["run", "--directory", "/path/to/bitbucket-mcp", "python", "server.py"]
}
}
}
Available Tools
Configuration
setup_bitbucket
Configure Bitbucket credentials.
setup_bitbucket(
workspace="your-workspace",
username="your-email@example.com",
api_token="your-api-token"
)
get_config_status
Check if Bitbucket is configured.
get_config_status()
# Returns: { "configured": true, "workspace": "...", "username": "..." }
Workspace
list_workspace_members
List members of a workspace. Useful for finding reviewers.
list_workspace_members(
workspace="your-workspace", # optional if configured
page=1,
pagelen=50
)
# Returns: { "members": [{ "uuid": "...", "display_name": "...", "account_id": "..." }] }
get_default_reviewers
Get the default reviewers configured for a repository.
get_default_reviewers(
repo_slug="my-repo",
workspace="your-workspace" # optional if configured
)
# Returns: { "default_reviewers": [{ "uuid": "...", "display_name": "..." }] }
Pull Requests
create_pull_request
Create a new Pull Request. Automatically includes default reviewers.
create_pull_request(
repo_slug="my-repo",
title="Feature: Add new functionality",
source_branch="feature/my-feature",
destination_branch="main", # optional, defaults to "main"
description="This PR adds...", # optional
reviewers=["uuid-1", "uuid-2"], # optional, additional reviewers
use_default_reviewers=True, # optional, defaults to True
workspace="your-workspace" # optional if configured
)
list_pull_requests
List PRs for a repository.
list_pull_requests(
repo_slug="my-repo",
state="OPEN", # OPEN, MERGED, DECLINED, SUPERSEDED, or ALL
workspace="your-workspace", # optional if configured
page=1,
pagelen=25
)
get_pull_request
Get details of a specific PR.
get_pull_request(
repo_slug="my-repo",
pr_id=123,
workspace="your-workspace" # optional if configured
)
update_pull_request
Update an existing PR.
update_pull_request(
repo_slug="my-repo",
pr_id=123,
title="New title", # optional
description="New description", # optional
destination_branch="develop", # optional
reviewers=["uuid-1", "uuid-2"], # optional, replaces current reviewers
close_source_branch=True, # optional
workspace="your-workspace" # optional if configured
)
Reviews
approve_pull_request
Approve a PR.
approve_pull_request(
repo_slug="my-repo",
pr_id=123,
workspace="your-workspace" # optional if configured
)
unapprove_pull_request
Remove your approval from a PR.
unapprove_pull_request(
repo_slug="my-repo",
pr_id=123,
workspace="your-workspace" # optional if configured
)
request_changes_pull_request
Request changes on a PR.
request_changes_pull_request(
repo_slug="my-repo",
pr_id=123,
workspace="your-workspace" # optional if configured
)
add_pull_request_comment
Add a comment to a PR (supports markdown).
add_pull_request_comment(
repo_slug="my-repo",
pr_id=123,
comment="Looks good! Just one suggestion...",
workspace="your-workspace" # optional if configured
)
Example Usage with Claude
-
First time setup:
"Set up Bitbucket with my workspace 'mycompany', username 'me@example.com', and API token 'abc123'"
-
Create a PR:
"Create a PR in my-repo from feature/login to main titled 'Add user login'"
-
List open PRs:
"Show me all open PRs in my-repo"
-
Review a PR:
"Approve PR #42 in my-repo"
-
Add a comment:
"Add a comment to PR #42 saying 'LGTM!'"
-
Find reviewers:
"List all members in my workspace so I can add them as reviewers"
Security
- Credentials are stored in
~/.bitbucket-mcp/config.jsonwith 600 permissions (owner-only access) - API tokens are never logged or exposed in error messages
- Environment variables are supported for CI/CD scenarios
License
MIT License - see LICENSE for details.