Bitbucket MCP Server
MCP server for Bitbucket API operations. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.
Language Versions
This repository contains both TypeScript and Python implementations:
| Version | Directory | Status | Installation |
|---|---|---|---|
| TypeScript | /typescript | ✅ Recommended (Smithery) | npm install -g mcp-server-bitbucket |
| Python | /python | ✅ Stable | pipx install mcp-server-bitbucket |
Note: The TypeScript version is used for Smithery deployments. Both versions provide identical functionality.
Features
- Repositories: get, create, delete, list, update (move to project, rename)
- Pull Requests: create, get, list, merge, approve, decline, request changes, comments, diff
- Pipelines: trigger, get status, list, view logs, stop
- Branches: list, get
- Projects: list, get
- Commits: list, get details, compare/diff between branches
- Commit Statuses: get build statuses, create status (CI/CD integration)
- Deployments: list environments, get environment details, deployment history
- Webhooks: list, create, get, delete
- Tags: list, create, delete
- Branch Restrictions: list, create, delete branch protection rules
- Source Browsing: read files, list directories without cloning
- Repository Permissions: manage user and group permissions
- Pipeline Variables: manage CI/CD environment variables
- MCP Prompts: reusable workflow templates (code review, release notes, etc.)
- MCP Resources: browsable workspace data
Quick Start
TypeScript (Recommended for Smithery)
# Install globally
npm install -g mcp-server-bitbucket
# Or run directly with npx
npx mcp-server-bitbucket
Python
# Install with pipx
pipx install mcp-server-bitbucket
# Configure Claude Code
claude mcp add bitbucket -s user \
-e BITBUCKET_WORKSPACE=your-workspace \
-e BITBUCKET_EMAIL=your-email@example.com \
-e BITBUCKET_API_TOKEN=your-api-token \
-- mcp-server-bitbucket
Full Installation Guide - Includes API token creation, permissions setup, and troubleshooting.
Configuration
Environment Variables
| Variable | Required | Description |
|---|---|---|
BITBUCKET_WORKSPACE | ✅ | Bitbucket workspace slug |
BITBUCKET_EMAIL | ✅ | Account email for Basic Auth |
BITBUCKET_API_TOKEN | ✅ | Repository access token |
API_TIMEOUT | Request timeout in seconds (default: 30) | |
MAX_RETRIES | Max retry attempts for rate limiting (default: 3) |
Claude Code CLI
# TypeScript version
claude mcp add bitbucket -s user \
-e BITBUCKET_WORKSPACE=your-workspace \
-e BITBUCKET_EMAIL=your-email@example.com \
-e BITBUCKET_API_TOKEN=your-api-token \
-- npx mcp-server-bitbucket
# Python version
claude mcp add bitbucket -s user \
-e BITBUCKET_WORKSPACE=your-workspace \
-e BITBUCKET_EMAIL=your-email@example.com \
-e BITBUCKET_API_TOKEN=your-api-token \
-- mcp-server-bitbucket
Cursor IDE
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["mcp-server-bitbucket"],
"env": {
"BITBUCKET_WORKSPACE": "your-workspace",
"BITBUCKET_EMAIL": "your-email@example.com",
"BITBUCKET_API_TOKEN": "your-api-token"
}
}
}
}
Available Tools (58 total)
Repositories
| Tool | Description |
|---|---|
list_repositories | List and search repositories |
get_repository | Get repository details |
create_repository | Create a new repository |
delete_repository | Delete a repository |
update_repository | Update repo settings |
Pull Requests
| Tool | Description |
|---|---|
list_pull_requests | List PRs |
get_pull_request | Get PR details |
create_pull_request | Create a new PR |
merge_pull_request | Merge a PR |
approve_pr | Approve a PR |
unapprove_pr | Remove approval |
request_changes_pr | Request changes |
decline_pr | Decline a PR |
list_pr_comments | List comments |
add_pr_comment | Add comment |
get_pr_diff | Get the diff |
Pipelines
| Tool | Description |
|---|---|
list_pipelines | List recent runs |
get_pipeline | Get status |
get_pipeline_logs | View logs |
trigger_pipeline | Trigger a run (supports custom pipelines and commit triggers) |
stop_pipeline | Stop pipeline |
list_pipeline_variables | List variables |
get_pipeline_variable | Get variable |
create_pipeline_variable | Create variable |
update_pipeline_variable | Update variable |
delete_pipeline_variable | Delete variable |
trigger_pipeline Parameters
| Parameter | Type | Description |
|---|---|---|
repo_slug | string | Repository slug (required) |
branch | string | Branch to run on (default: main). Mutually exclusive with commit |
commit | string | Commit hash to run on. Mutually exclusive with branch |
custom_pipeline | string | Name from custom: section in bitbucket-pipelines.yml |
variables | array | Variables as [{key, value, secured?}] |
Examples:
# Default pipeline on main
trigger_pipeline(repo_slug="my-repo")
# Custom pipeline
trigger_pipeline(repo_slug="my-repo", custom_pipeline="deploy-staging")
# Custom pipeline on specific commit with variables
trigger_pipeline(
repo_slug="my-repo",
commit="abc123def",
custom_pipeline="deploy-prod",
variables=[
{"key": "ENV", "value": "production"},
{"key": "SECRET", "value": "xxx", "secured": True}
]
)
Branches, Commits, Tags
| Tool | Description |
|---|---|
list_branches | List branches |
get_branch | Get branch details |
list_commits | List commits |
get_commit | Get commit details |
compare_commits | Compare branches |
get_commit_statuses | Get build statuses |
create_commit_status | Report CI status |
list_tags | List tags |
create_tag | Create a tag |
delete_tag | Delete a tag |
And more...
- Deployments:
list_environments,get_environment,list_deployment_history - Webhooks:
list_webhooks,create_webhook,get_webhook,delete_webhook - Branch Restrictions:
list_branch_restrictions,create_branch_restriction,delete_branch_restriction - Source Browsing:
get_file_content,list_directory - Permissions: User and group permission management (8 tools)
- Projects:
list_projects,get_project
MCP Prompts
Reusable workflow templates:
| Prompt | Description |
|---|---|
code_review | Comprehensive PR code review |
release_notes | Generate changelog between versions |
pipeline_debug | Debug failed CI/CD pipelines |
repo_summary | Complete repository status overview |
MCP Resources
Browsable workspace data:
| Resource URI | Description |
|---|---|
bitbucket://repositories | List all repos |
bitbucket://repositories/{repo} | Repository details |
bitbucket://repositories/{repo}/branches | Branch list |
bitbucket://repositories/{repo}/pull-requests | Open PRs |
bitbucket://projects | List all projects |
Development
TypeScript
cd typescript
npm install
npm run build
npm run dev # Watch mode
Python
cd python
uv sync
uv run python -m src.server
Creating a Bitbucket API Token
- Go to your repository in Bitbucket
- Navigate to Repository settings > Access tokens
- Click Create Repository Access Token
- Select permissions:
- Repository: Read, Write, Admin, Delete
- Pull requests: Read, Write
- Pipelines: Read, Write
- Copy the token immediately
Author
Built by Javier Aguilar - AI Agent Architect specializing in multi-agent orchestration and MCP development.
License
MIT