Bitbucket MCP Server

<!-- mcp-name: io.github.JaviMaligno/bitbucket -->

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

1. Go to your repository in Bitbucket
2. Navigate to Repository settings > Access tokens
3. Click Create Repository Access Token
4. Select permissions:
- Repository: Read, Write, Admin, Delete
- Pull requests: Read, Write
- Pipelines: Read, Write
5. Copy the token immediately

Author

Built by Javier Aguilar - AI Agent Architect specializing in multi-agent orchestration and MCP development.

License

MIT