mcp-server-bitbucket 0.1.8

MCP server for Bitbucket API operations

Bitbucket MCP Server

MCP server for Bitbucket API operations. Works with Claude Code, Claude Desktop, and any MCP-compatible client.

Features

• Repositories: get, create, delete, list, update (move to project, rename)
• Pull Requests: create, get, list, merge
• Pipelines: trigger, get status, list, view logs, stop
• Branches: list, get
• Projects: list, get

Quick Start

# Install
pipx install mcp-server-bitbucket

# Configure Claude Code
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=[e-mail] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

Full Installation Guide - Includes API token creation, permissions setup, and troubleshooting.

Available Tools

Tool	Description
list_repositories	List and search repositories (supports fuzzy name matching)
get_repository	Get repository details
create_repository	Create a new repository
delete_repository	Delete a repository
list_branches	List branches in a repo
get_branch	Get branch details
list_projects	List projects in workspace
get_project	Get project details
update_repository	Update repo settings (project, visibility, description, name)
list_pull_requests	List PRs (open, merged, etc.)
get_pull_request	Get PR details
create_pull_request	Create a new PR
merge_pull_request	Merge a PR
list_pipelines	List recent pipeline runs
get_pipeline	Get pipeline status
get_pipeline_logs	View pipeline logs
trigger_pipeline	Trigger a pipeline run
stop_pipeline	Stop a running pipeline

Example Usage

Once configured, ask Claude to:

• "List all repositories in my workspace"
• "Search for repositories with 'api' in the name"
• "Find all private repos containing 'test'"
• "List all projects in the workspace"
• "Move repository my-repo to project DS"
• "Show me open pull requests in my-repo"
• "Create a PR from feature-branch to main"
• "Trigger a pipeline on the develop branch"
• "What's the status of the latest pipeline?"
• "Merge PR #42 using squash strategy"

Repository Search

The list_repositories tool supports flexible searching:

# Simple fuzzy search by name
list_repositories(search="api")  # Finds repos with "api" in name

# Advanced Bitbucket query syntax
list_repositories(query='name ~ "test" AND is_private = true')

# Filter by project
list_repositories(project_key="MYPROJECT")

Query syntax supports: name ~ "term", is_private = true/false, AND, OR

Installation Options

From PyPI (Recommended)

pipx install mcp-server-bitbucket
# or
pip install mcp-server-bitbucket

From Source

git clone [e-mail]:simplekyc/bitbucket-mcp.git
cd bitbucket-mcp
poetry install

Configuration

Claude Code CLI (Recommended)

claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=[e-mail] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

Manual Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "mcp-server-bitbucket",
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_EMAIL": "[e-mail]",
        "BITBUCKET_API_TOKEN": "your-api-token"
      }
    }
  }
}

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

See the full installation guide for detailed instructions.

HTTP Server (Cloud Run)

For deploying as an HTTP API:

# Run locally
poetry run uvicorn src.http_server:app --reload --port 8080

# Deploy to Cloud Run
gcloud run deploy bitbucket-mcp-service \
  --source . \
  --region australia-southeast1 \
  --set-secrets "BITBUCKET_EMAIL=bitbucket-email:latest,BITBUCKET_API_TOKEN=bitbucket-token:latest"

Development

Requirements

• Python 3.11+
• Poetry for dependency management
• PyPI account for publishing

Setup

git clone [e-mail]:simplekyc/bitbucket-mcp.git
cd bitbucket-mcp
poetry install

Running Locally

# MCP server (stdio mode)
poetry run python -m src.server

# HTTP server
poetry run uvicorn src.http_server:app --reload --port 8080

Publishing to PyPI

1. Get a PyPI API Token:

   • Go to https://pypi.org/manage/account/token/
   • Create a token with scope "Entire account" (first time) or project-specific
   • Configure Poetry: poetry config pypi-token.pypi pypi-YOUR_TOKEN

2. Bump version in pyproject.toml

3. Build and publish:

   poetry build
   poetry publish
   

4. Tag the release:

   git tag v0.x.x
   git push origin v0.x.x
   

Links

• PyPI Package
• Installation Guide
• Bitbucket Repository

License

MIT