Content
# Bitbucket MCP Server
A FastMCP server for comprehensive Bitbucket Cloud API integration. Manage pull requests, repositories, branches, commits, pipelines, issues, webhooks, snippets, and more directly from Claude.
## Features
- **User & Account**: Get current user info, user profiles, and repository permissions
- **Repository Management**: List, create, update, delete, and fork repositories
- **Branch & Tag Management**: Create/delete branches and tags, view branching model
- **Commits & Build Status**: List commits, view diffs, manage build statuses
- **Pull Request Lifecycle**: Create, update, merge, and decline PRs
- **Code Review**: Approve, request changes, add/remove reviewers
- **Comments**: Add, read, reply to, and delete comments (including inline code comments)
- **Diff & Code**: View diffs, file changes, commits, and file contents
- **Merge Status**: Check if PR can be merged, view conflicts and blockers
- **Pipelines (CI/CD)**: List, trigger, stop pipelines; view steps and logs; manage variables
- **Workspace & Projects**: List workspaces, manage projects, search code
- **Issues**: Create, update, list issues; manage issue comments
- **Webhooks**: Create, list, and delete repository and workspace webhooks
- **Snippets**: Create, list, get, and delete code snippets
## Installation
### From PyPI (Recommended)
```bash
pip install bitbucket-mcp
```
Or run directly with uvx (no install needed):
```bash
uvx bitbucket-mcp
```
## Getting an API Token
1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Give it a name (e.g., "Bitbucket MCP")
4. 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
```bash
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`:
```json
{
"mcpServers": {
"bitbucket": {
"command": "uvx",
"args": ["bitbucket-mcp"]
}
}
}
```
Or if installed with pip:
```json
{
"mcpServers": {
"bitbucket": {
"command": "bitbucket-mcp"
}
}
}
```
## Available Tools (77 total)
### Configuration (2 tools)
| Tool | Description |
|------|-------------|
| `setup_bitbucket` | Configure Bitbucket credentials |
| `get_config_status` | Check configuration status |
### User & Account (3 tools)
| Tool | Description |
|------|-------------|
| `get_current_user` | Get authenticated user's profile |
| `get_user_profile` | Get a user's public profile |
| `get_user_permissions` | Get current user's repository permissions |
### Repository Management (7 tools)
| Tool | Description |
|------|-------------|
| `list_repositories` | List repositories in a workspace |
| `get_repository` | Get detailed repository info |
| `create_repository` | Create a new repository |
| `update_repository` | Update repository settings |
| `delete_repository` | Delete a repository |
| `fork_repository` | Fork a repository |
| `list_repository_forks` | List forks of a repository |
### Branch & Tag Management (7 tools)
| Tool | Description |
|------|-------------|
| `list_branches` | List branches in a repository |
| `create_branch` | Create a new branch |
| `delete_branch` | Delete a branch |
| `list_tags` | List tags in a repository |
| `create_tag` | Create a new tag |
| `delete_tag` | Delete a tag |
| `get_branching_model` | Get branching model configuration |
### Commits & Build Status (8 tools)
| Tool | Description |
|------|-------------|
| `get_file_contents` | Get file contents from a branch/commit |
| `list_commits` | List commits in a repository |
| `get_commit` | Get details of a specific commit |
| `get_commit_diff` | Get diff for a commit or range |
| `get_commit_diffstat` | Get diffstat for a commit or range |
| `list_commit_statuses` | List build statuses for a commit |
| `create_build_status` | Create a build status for a commit |
| `list_commit_comments` | List comments on a commit |
### Pull Requests (20 tools)
| Tool | Description |
|------|-------------|
| `create_pull_request` | Create a new PR with default reviewers |
| `list_pull_requests` | List PRs for a repository |
| `get_pull_request` | Get PR details |
| `update_pull_request` | Update/edit a PR |
| `approve_pull_request` | Approve a PR |
| `unapprove_pull_request` | Remove approval from a PR |
| `request_changes_pull_request` | Request changes on a PR |
| `add_pull_request_comment` | Add a comment to a PR |
| `get_pull_request_comments` | Get comments from a PR |
| `get_pull_request_diffstat` | Get summary of files changed |
| `get_pull_request_diff` | Get code diff for a PR |
| `merge_pull_request` | Merge a PR |
| `decline_pull_request` | Decline/close a PR |
| `reply_to_comment` | Reply to a specific comment |
| `add_inline_comment` | Add inline comment on code |
| `delete_comment` | Delete a comment |
| `get_pull_request_activity` | Get PR activity timeline |
| `get_pull_request_commits` | List commits in a PR |
| `add_reviewer` | Add a reviewer to a PR |
| `remove_reviewer` | Remove a reviewer from a PR |
| `get_pull_request_merge_status` | Check if PR can be merged |
### Pipelines / CI/CD (8 tools)
| Tool | Description |
|------|-------------|
| `list_pipelines` | List pipelines for a repository |
| `get_pipeline` | Get pipeline details |
| `trigger_pipeline` | Trigger a new pipeline run |
| `stop_pipeline` | Stop a running pipeline |
| `list_pipeline_steps` | List steps in a pipeline |
| `get_pipeline_step_log` | Get log output for a step |
| `list_pipeline_variables` | List pipeline variables |
| `create_pipeline_variable` | Create a pipeline variable |
### Workspace & Projects (10 tools)
| Tool | Description |
|------|-------------|
| `list_workspace_members` | List workspace members |
| `get_default_reviewers` | Get default reviewers for a repo |
| `list_workspaces` | List all accessible workspaces |
| `get_workspace_details` | Get workspace details |
| `list_workspace_permissions` | List workspace permissions |
| `list_projects` | List projects in a workspace |
| `get_project` | Get project details |
| `create_project` | Create a new project |
| `search_code` | Search code across repositories |
### Issues (6 tools)
| Tool | Description |
|------|-------------|
| `list_issues` | List issues in a repository |
| `create_issue` | Create a new issue |
| `get_issue` | Get issue details |
| `update_issue` | Update an issue |
| `list_issue_comments` | List comments on an issue |
| `add_issue_comment` | Add a comment to an issue |
### Webhooks (4 tools)
| Tool | Description |
|------|-------------|
| `list_webhooks` | List repository webhooks |
| `create_webhook` | Create a repository webhook |
| `delete_webhook` | Delete a repository webhook |
| `list_workspace_webhooks` | List workspace webhooks |
### Snippets (4 tools)
| Tool | Description |
|------|-------------|
| `list_snippets` | List snippets in a workspace |
| `create_snippet` | Create a new snippet |
| `get_snippet` | Get snippet details |
| `delete_snippet` | Delete a snippet |
## Example Usage with Claude
1. **First time setup:**
> "Set up Bitbucket with my workspace 'mycompany', username 'me@example.com', and API token 'abc123'"
2. **List repositories:**
> "Show me all repositories in my workspace"
3. **Create a PR:**
> "Create a PR in my-repo from feature/login to main titled 'Add user login'"
4. **Review a PR:**
> "Approve PR #42 in my-repo"
5. **Check merge status:**
> "Can PR #42 be merged? Are there any conflicts?"
6. **Merge a PR:**
> "Squash merge PR #42 and delete the source branch"
7. **Pipeline operations:**
> "Trigger a pipeline on the main branch for my-repo"
> "Show me the logs for the last pipeline run"
8. **Branch management:**
> "Create a branch 'feature/new-api' from main in my-repo"
> "List all tags in my-repo"
9. **Issue tracking:**
> "Create a bug issue titled 'Login fails on mobile' in my-repo"
> "Show me all open issues in my-repo"
10. **Code search:**
> "Search for 'TODO' across all repositories in my workspace"
## Security
- Credentials are stored in `~/.bitbucket-mcp/config.json` with 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](LICENSE) for details.
