hlavaceklab/bitbucket-mcp repository overview

⁠Bitbucket MCP

MCP (Model Context Protocol) server for Bitbucket Cloud API. Enables AI assistants like Claude to interact with Bitbucket repositories, pull requests, and branches.

⁠Features

• 🔀 Pull Requests - Create, list, merge, approve, decline, and comment on PRs
• 🌿 Branches - List repository branches
• 📁 Repositories - Get repository information
• 🔍 Diffs - View PR diffs and changes
• 💬 Comments - Add and list PR comments
• 🚦 Pipelines - Read run status and logs; trigger and stop runs (opt-in)

⁠Installation

Install from source:

git clone https://github.com/martinhlavacek/bitbucket-mcp.git
cd bitbucket-mcp
pip install -e .

⁠Configuration

⁠Bitbucket API Token

1. Go to Atlassian Account Settings⁠
2. Click Create API token with scopes
3. Select Bitbucket as the application
4. Add required scopes:
   • repository:read
   • repository:write
   • pullrequest:read
   • pullrequest:write
5. Copy the token (it's only shown once!)

⁠Environment Variables

export BITBUCKET_EMAIL="[email protected]"
export BITBUCKET_API_TOKEN="your-api-token"
export BITBUCKET_WORKSPACE="your-workspace"  # optional, can be passed per-request

⁠Usage

⁠With Claude Code

Via CLI:

claude mcp add --transport stdio \
  --env [email protected] \
  --env BITBUCKET_API_TOKEN=your-api-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  bitbucket -- python -m bitbucket_mcp

Or add to your MCP configuration file:

{
  "mcpServers": {
    "bitbucket": {
      "command": "python",
      "args": ["-m", "bitbucket_mcp"],
      "env": {
        "BITBUCKET_EMAIL": "[email protected]",
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

⁠Standalone

python -m bitbucket_mcp

⁠Docker

⁠Run with Docker

docker run -d \
  -p 8000:8000 \
  -e [email protected] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  hlavaceklab/bitbucket-mcp:latest

⁠Connect Claude Code to Remote Server

Via CLI:

claude mcp add --transport http bitbucket http://localhost:8000/mcp

Via JSON config:

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://your-server:8000/mcp"
    }
  }
}

⁠Docker Compose

Create a .env file with your credentials:

[email protected]
BITBUCKET_API_TOKEN=your-api-token
BITBUCKET_WORKSPACE=your-workspace

Run with Docker Compose:

docker compose up -d

⁠Build Locally

docker build -t bitbucket-mcp .
docker run -d -p 8000:8000 \
  -e [email protected] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  bitbucket-mcp

⁠Monitoring Endpoints

⁠Available Tools

⁠Pipeline write operations

Triggering a pipeline is the one operation here that can spend build minutes and deploy to an environment, so it is off by default and gated by two independent settings.

export BITBUCKET_ALLOW_PIPELINE_TRIGGER="true"
export BITBUCKET_PIPELINE_ALLOWLIST="my-api:ci,my-api:preview,web:ci"
export BITBUCKET_ALLOW_PIPELINE_STOP="true"   # this is the default

The allowlist is scoped per repository (repo-slug:pipeline-name) because one server instance serves every repository - a bare pipeline name would let a deploy allowed for a staging repo also run the production deploy of another one. An empty allowlist means no custom pipeline may run, not every one.

Running a branch's default pipeline needs no allowlist entry: it runs what a push to that branch would have run anyway, so it cannot deploy anything a push could not.

⁠Where to set these

The settings are read from the environment of the server process, so they belong wherever that process is started - not in the client that connects to it.

Running the server over HTTP (Docker, shared host) rather than stdio, the client config holds only a URL and no environment at all; the variables go on the host running the container:

# docker-compose.yml on the server
services:
  bitbucket-mcp:
    image: hlavaceklab/bitbucket-mcp:latest
    environment:
      - BITBUCKET_ALLOW_PIPELINE_TRIGGER=true
      - BITBUCKET_PIPELINE_ALLOWLIST=my-api:ci,web:preview

docker compose up -d   # a restart is required; the config is read from the process env

⁠Development

# Clone
git clone https://github.com/martinhlavacek/bitbucket-mcp.git
cd bitbucket-mcp

# Setup
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Test
pytest

# Lint
ruff check .

⁠Contributing

Contributions are welcome! Please read our Contributing Guide⁠ and Code of Conduct⁠.

⁠License

MIT License - see LICENSE⁠ for details.

⁠Related Projects

• FastMCP⁠ - Python framework for MCP servers
• MCP Specification⁠ - Model Context Protocol
• GitHub MCP⁠ - Official GitHub MCP server