mcp-bitbucket

  

Python MCP (Model Context Protocol) server for Bitbucket Cloud (REST API v2.0), built with FastMCP. It exposes 35 tools covering repositories, pull requests (including comments, drafts, and pending reviews), branching models, and pipelines — enabling AI clients (Cursor, Claude Code, etc.) to safely automate Bitbucket workflows.

---

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Running the Server
• Docker Usage
• Multi-Project Setup
• Tools Reference
• Use with AI Clients
• Debugging with MCP Inspector
• Architecture
• Troubleshooting
• Security
• License

---

Features

• Full Bitbucket Cloud REST API v2.0 coverage for common workflows
• Two transport modes: stdio (for local AI clients) and SSE/HTTP (for Docker/remote)
• Draft pull requests and pending (unpublished) comments support
• Cross-repository pending review detection
• Branching model management at both repository and project levels
• Pipeline management: trigger, stop, inspect runs, steps, and logs
• Built-in health check with connectivity validation
• Multi-project support with separate credentials per workspace
• Docker-ready with health checks, resource limits, and non-root user

---

Requirements

• Python 3.10+
• uv package manager (pipx install uv or follow uv docs)
• Bitbucket Cloud account with one of:
• App Password (recommended) for BITBUCKET_USERNAME / BITBUCKET_PASSWORD
• OAuth token via BITBUCKET_TOKEN

Recommended App Password Scopes

| Scope | Required for | |-------|-------------| | repository:read | Listing repos, branching models | | pullrequest:read | Reading PRs, comments, diffs, commits | | pullrequest:write | Creating/updating/merging PRs, comments | | pipeline:read | Listing and inspecting pipeline runs | | pipeline:write | Triggering and stopping pipelines |

---

Installation

# Clone the repository
git clone https://github.com/webboy/mcp-bitbucket.git
cd mcp-bitbucket

# Install in editable mode
uv pip install -e .

Dependencies

| Package | Purpose | |---------|---------| | mcp[cli]>=1.2.0 | MCP SDK with CLI support | | httpx>=0.27 | HTTP client for Bitbucket API | | pydantic>=2.7 | Data validation and tool parameter schemas | | structlog>=24.1.0 | Structured logging | | uvicorn>=0.30.0 | ASGI server for SSE transport | | starlette>=0.37.0 | ASGI framework |

---

Configuration

All configuration is done via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | BITBUCKET_URL | https://api.bitbucket.org/2.0 | Bitbucket Cloud API base URL | | BITBUCKET_TOKEN | — | OAuth Bearer token (alternative to username/password) | | BITBUCKET_USERNAME | — | Bitbucket username (for App Password auth) | | BITBUCKET_PASSWORD | — | Bitbucket App Password | | BITBUCKET_WORKSPACE | — | Default workspace slug (optional but convenient) | | MCP_TRANSPORT | stdio | Transport type: stdio or sse | | MCP_HOST | 0.0.0.0 | Host to bind SSE server | | MCP_PORT | 9000 | Port for SSE server | | FASTMCP_LOG_LEVEL | INFO | Log level: DEBUG, INFO, WARNING, ERROR |

Note: Either BITBUCKET_TOKEN or BITBUCKET_USERNAME + BITBUCKET_PASSWORD must be set. The BITBUCKET_USERNAME is also required for the getPendingReviewPRs tool to identify the current reviewer.

---

Running the Server

stdio mode (default)

BITBUCKET_USERNAME='<user>' \
BITBUCKET_PASSWORD='<app_password>' \
BITBUCKET_WORKSPACE='<workspace>' \
uv run mcp-bitbucket

The server uses stdio and waits for an MCP client to connect.

SSE/HTTP mode

BITBUCKET_USERNAME='<user>' \
BITBUCKET_PASSWORD='<app_password>' \
BITBUCKET_WORKSPACE='<workspace>' \
uv run mcp-bitbucket --transport sse --port 9000

The server starts an HTTP endpoint at http://0.0.0.0:9000/sse.

CLI Arguments

| Argument | Default | Description | |----------|---------|-------------| | --transport | stdio (or MCP_TRANSPORT env) | stdio or sse | | --host | 0.0.0.0 (or MCP_HOST env) | Bind host for SSE | | --port | 9000 (or MCP_PORT env) | Bind port for SSE |

---

Docker Usage (HTTP/SSE Transport)

The MCP server runs in a Docker container using HTTP/SSE transport, allowing a single long-running container that handles multiple client connections.

Quick Start

1. Create environment file:

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

1. Build and start the container:

docker-compose up -d --build

1. Configure your AI client (e.g., Cursor ~/.cursor/mcp.json):

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://localhost:9000/sse"
    }
  }
}

1. Restart your AI client — The Bitbucket MCP server should now be available!

Manual Docker Commands

# Build the image
docker build -t mcp-bitbucket:latest .

# Run with docker-compose
docker-compose up -d          # Start in background
docker-compose logs -f         # View logs
docker-compose down            # Stop

# Run directly
docker run -d \
  --name mcp-bitbucket \
  -p 9000:9000 \
  -e BITBUCKET_USERNAME=your_username \
  -e BITBUCKET_PASSWORD=your_app_password \
  -e BITBUCKET_WORKSPACE=your_workspace \
  -e MCP_TRANSPORT=sse \
  mcp-bitbucket:latest

Health Check

curl http://localhost:9000/sse

Container Management

docker ps | grep mcp-bitbucket   # Check if running
docker logs mcp-bitbucket        # View logs
docker restart mcp-bitbucket     # Restart
docker stop mcp-bitbucket && docker rm mcp-bitbucket  # Stop and remove

Benefits of HTTP/SSE Transport

• Single container — one long-running container handles all requests
• Multiple connections — clients can connect/reconnect without spawning new containers
• Better performance — no container startup overhead per request
• Easier debugging — view logs with docker logs
• Health monitoring — built-in health checks (30s interval)
• Resource limits — default 512MB memory limit, 128MB reserved

---

Multi-Project Setup

Run multiple containers with different Bitbucket credentials for separate projects:

1. Create project-specific env files:

cp .env.project1.example .env.project1
cp .env.project2.example .env.project2
# Edit each with the appropriate credentials

1. Start both containers:

docker compose -f docker-compose.project1.yml up -d
docker compose -f docker-compose.project2.yml up -d

1. Configure your AI client with both servers:

{
  "mcpServers": {
    "bitbucket-project1": {
      "url": "http://localhost:9000/sse"
    },
    "bitbucket-project2": {
      "url": "http://localhost:9001/sse"
    }
  }
}

1. Manage individually:

docker compose -f docker-compose.project1.yml down      # Stop project1
docker compose -f docker-compose.project2.yml logs -f    # Logs for project2

---

Tools Reference

All tools return MCP-compatible responses (text content with pretty-printed JSON, or raw text for diffs/logs). Errors are returned as structured ERROR: <ExceptionType>: <message> text.

Health (1 tool)

| Tool | Description | |------|-------------| | health | Validates configuration and Bitbucket connectivity. Checks credentials and workspace access. |

Repositories (2 tools)

| Tool | Description | |------|-------------| | listRepositories | List repositories in a workspace. Filter by name (contains match) and limit results (1–100). | | getRepository | Get full repository details by workspace and repo slug. |

Pull Requests (17 tools)

| Tool | Description | |------|-------------| | getPullRequests | List PRs for a repository. Filter by state (OPEN, MERGED, DECLINED, SUPERSEDED) and limit. | | createPullRequest | Create a PR with title, description, source/target branches, optional reviewers. Supports draft=True. | | getPullRequest | Get a single PR by ID. | | updatePullRequest | Update PR title and/or description. | | getPullRequestActivity | List activity feed (comments, approvals, status changes) for a PR. | | approvePullRequest | Approve a PR as the current user. | | unapprovePullRequest | Remove your approval from a PR. | | declinePullRequest | Decline (close) a PR with an optional message. | | mergePullRequest | Merge a PR with optional commit message and merge strategy (merge-commit, squash, fast-forward). | | getPullRequestComments | List all comments on a PR. | | getPullRequestCommits | List commits included in a PR. | | getPullRequestDiff | Get the unified diff for a PR (raw text). | | addPullRequestComment | Add a comment to a PR. Supports inline file/line comments and pending (draft) comments. | | addPendingPullRequestComment | Add a pending (unpublished) comment to a PR. Shorthand for addPullRequestComment with pending=True. | | publishPendingComments | Publish all pending comments on a PR. | | createDraftPullRequest | Create a draft PR (shorthand for createPullRequest with draft=True). | | publishDraftPullRequest | Publish a draft PR (convert to ready for review). | | convertTodraft | Convert an open PR back to draft. | | getPendingReviewPRs | List PRs awaiting your review across all (or specified) repositories in a workspace. Requires BITBUCKET_USERNAME. |

Branching Models (7 tools)

| Tool | Description | |------|-------------| | getRepositoryBranchingModel | Get the repository-level branching model (effective settings). | | getRepositoryBranchingModelSettings | Get raw repository branching model settings (may inherit from project). | | updateRepositoryBranchingModelSettings | Update repository branching model: development/production branches and branch types. | | getEffectiveRepositoryBranchingModel | Resolve the effective branching model taking project-level inheritance into account. | | getProjectBranchingModel | Get project-level branching model (defaults for repositories). | | getProjectBranchingModelSettings | Get raw project branching model settings. | | updateProjectBranchingModelSettings | Update project branching model: development/production branches and branch types. |

Pipelines (8 tools)

| Tool | Description | |------|-------------| | listPipelineRuns | List pipeline runs. Filter by status (COMPLETED, FAILED, RUNNING), target branch, trigger type (PUSH, MANUAL), and limit. | | getPipelineRun | Get details for a specific pipeline run by UUID. | | runPipeline | Trigger a pipeline run for a target branch/commit with optional pipeline variables. | | stopPipeline | Stop a running pipeline by UUID. | | getPipelineSteps | List all steps for a pipeline run. | | getPipelineStep | Get details for a specific pipeline step. | | getPipelineStepLogs | Get raw logs for a pipeline step (plain text). |

---

Use with AI Clients

Cursor (Docker — Recommended)

See Docker Usage above. Configure ~/.cursor/mcp.json: ``json { "mcpServers": { "bitbucket": { "url": "http://localhost:9000/sse" } } } ``

Cursor / Claude Code (Direct UV — Development)

If the client runs inside the same environment (e.g., Ubuntu/WSL2), use an absolute path to uv: ``json { "mcpServers": { "bitbucket": { "command": "/home/<user>/.local/bin/uv", "args": ["run", "--with-editable", "/path/to/mcp-bitbucket", "mcp-bitbucket"], "env": { "BITBUCKET_URL": "https://api.bitbucket.org/2.0", "BITBUCKET_USERNAME": "your_username", "BITBUCKET_PASSWORD": "your_app_password", "BITBUCKET_WORKSPACE": "your_workspace", "FASTMCP_LOG_LEVEL": "DEBUG" } } } } ``

Cursor on Windows (WSL Bridge)

If Cursor runs on Windows (outside WSL), bridge to WSL: ``json { "mcpServers": { "bitbucket": { "command": "wsl", "args": [ "bash", "-lc", "cd /home/<user>/projects/mcp/mcp-bitbucket && BITBUCKET_USERNAME='your_username' BITBUCKET_PASSWORD='your_app_password' BITBUCKET_WORKSPACE='your_workspace' /home/<user>/.local/bin/uv run mcp-bitbucket" ] } } } ``

---

Debug with MCP Inspector

Launch the MCP Inspector to interactively test tools:

BITBUCKET_USERNAME='<user>' \
BITBUCKET_PASSWORD='<app_password>' \
BITBUCKET_WORKSPACE='<workspace>' \
uv run --with mcp mcp dev src/app.py --with-editable .

Open the printed URL and call tools like health and listRepositories.

---

Architecture

mcp-bitbucket/
├── src/
│   ├── cli.py                # CLI entry point (argparse, transport selection)
│   ├── app.py                # FastMCP instance for MCP Inspector / dev
│   ├── server.py             # BitbucketMcpServer: tool registry + MCP handlers
│   ├── bitbucket_client.py   # BitbucketClient: thin httpx wrapper over REST v2.0
│   └── config.py             # BitbucketConfig dataclass + env loader
├── Dockerfile                # Python 3.10-slim, non-root user, SSE default
├── docker-compose.yml        # Default single-instance compose
├── docker-compose.project1.yml  # Multi-project compose (port 9000)
├── docker-compose.project2.yml  # Multi-project compose (port 9001)
├── .env.example              # Template for environment variables
├── pyproject.toml            # Project metadata and dependencies (hatchling)
└── LICENSE                   # MIT

Key Components

• BitbucketConfig — Immutable dataclass holding API URL, credentials, and default workspace. Loaded from environment variables.
• BitbucketClient — Synchronous HTTP client (httpx) that maps 1:1 to Bitbucket REST API v2.0 endpoints. Supports both token and App Password authentication.
• BitbucketMcpServer — Registers all 35 tools with FastMCP, wraps each call in error handling (_safe), and manages both stdio and SSE transports.
• cli.py — Entry point that parses CLI arguments, initializes config and server, and runs the selected transport.

---

Troubleshooting

| Problem | Solution | |---------|----------| | No tools visible in client | Ensure the command starts in your environment (use absolute path to uv). Set FASTMCP_LOG_LEVEL=DEBUG. | | 401/403 errors | Verify App Password scopes and workspace/repo access. | | Workspace missing errors | Set BITBUCKET_WORKSPACE env var or pass workspace argument to tools. | | Inspector won't connect | Ensure proxy health at http://localhost:6277/health returns {"status":"ok"}. If bridging from Windows to WSL, enable localhost forwarding. | | Container not starting | Check docker logs mcp-bitbucket for startup errors. Verify .env file exists and is populated. | | getPendingReviewPRs fails | Requires BITBUCKET_USERNAME to be set (identifies the current reviewer). |

---

Security

• Treat App Passwords and OAuth tokens as secrets. Never commit .env files — they are in .gitignore.
• The Docker image runs as a non-root user (mcp, UID 1000).
• Rotate credentials immediately if exposed.
• The server does not store or log credentials.

---

License

MIT — Copyright (c) 2025 Nemanja Milenković