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:

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

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

Pull Requests

Pipelines

trigger_pipeline Parameters

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

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:

MCP Resources

Browsable workspace data:

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

License

MIT