Bitbucket MCP

🚀 Bitbucket MCP Server (Python)

Connect Claude Code, VS Code (GitHub Copilot), Cursor, and any MCP-compatible AI assistant to your Bitbucket Cloud repositories. Review pull requests, monitor pipelines, and manage your code — all through natural language.

✨ Features

• 45 MCP tools — repositories, pull requests, comments, tasks, diffs, pipelines, build statuses, reviewers, draft PRs, batch review
• Slim responses — stripped API noise for lower LLM token usage
• Configurable — enable/disable tools via configs/tools.json or BITBUCKET_TOOLS_CONFIG env var
• Secure credentials — environment variables or system keychain

🚀 Quick Start

1. Install

The recommended way to run the server is via uvx (zero install, isolated environment):

# Always latest version
uvx --from bitbucket-mcp-py bitbucket-mcp

# Pin a specific version
uvx --from bitbucket-mcp-py==1.8.1 bitbucket-mcp

Why --from? The PyPI package is bitbucket-mcp-py but the command entry point is bitbucket-mcp. The --from flag tells uvx which package to install.

2. Configure credentials

Set the following environment variables (or use a .env file — see Credentials):

Get your API token at: https://id.atlassian.com/manage-profile/security/api-tokens

⚠️ Important Note

Use a scoped token, not a global one. When creating the token, select specific scopes (e.g. Repositories: Read, Pull requests: Read/Write). Global tokens without explicit scopes do not work with this MCP server.

3. Configure your AI assistant

Claude Code (recommended)

Option A — CLI (fastest):

claude mcp add bitbucket-mcp \
  -e BITBUCKET_USERNAME=your-email@example.com \
  -e BITBUCKET_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

Option B — JSON config (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (workspace) or ~/Library/Application Support/Code/User/mcp.json (global, macOS):

{
  "servers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

📦 Available Tools

Disabled by default: merge_pull_request (safety), stop_pipeline (safety), get_pull_request_patch (git am format — not useful for AI review), convert_pull_request_to_draft (not supported by Bitbucket API). Enable in configs/tools.json.

Custom tool configuration

By default the server reads configs/tools.json bundled with the package. You can point to a custom file at runtime without rebuilding:

export BITBUCKET_TOOLS_CONFIG=/path/to/my-tools.json

Fallback chain (first match wins):

1. BITBUCKET_TOOLS_CONFIG environment variable
2. Built-in configs/tools.json

Important Note

Fail-safe behaviour — If BITBUCKET_TOOLS_CONFIG is set but the file is missing or contains invalid JSON, the server raises an error on startup (explicit failure rather than silently ignoring the override). If the built-in default is missing, all tools are enabled.

💡 Usage Tip

get_pull_request_diff accepts an optional path parameter to filter the diff to a single file, reducing token usage by ~95% on large PRs:

get_pull_request_diff(repo_slug, pull_request_id, path="src/services/myService.ts")

📚 Credentials

Option 1: .env file (recommended)

cp .env.example .env
# Edit .env with your credentials

Option 2: System keychain (most secure)

pip install 'bitbucket-mcp-py[keyring]'
python3 -c "import keyring; keyring.set_password('bitbucket-mcp', 'bitbucket_token', 'YOUR_TOKEN')"

📦 Docker (Alternative)

If you prefer running the server in a container:

docker build -t bitbucket-mcp-py .
docker run -d --name bitbucket-mcp --env-file .env bitbucket-mcp-py

Then configure your AI assistant to use docker exec:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "bitbucket-mcp", "python", "-m", "src.main", "--transport", "stdio"]
    }
  }
}

🔧 Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/test_client.py -v

📚 Requirements

• Python 3.12+
• Bitbucket API token

📄 License

MIT

📚 References

• MCP Registry — Official MCP server registry
• PyPI Package — Python package
• MCP Python SDK
• Bitbucket API 2.0
• FastMCP Framework