bitbucket-mcp: Instructions file for Claude Code

CLAUDE.md - Bitbucket MCP Server

Project Overview

Name: bitbucket-mcp-py Type: MCP (Model Context Protocol) Server for Bitbucket API Version: 1.29.2 Python: 3.12+ Container Runtime: Podman (preferred) or Docker

Client Configuration (uvx — recommended)

Claude Code CLI:

claude mcp add bitbucket-mcp \
  -e [email protected] \
  -e BITBUCKET_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

Claude Code / GitHub Copilot JSON config:

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

OpenAI Codex TOML config (~/.codex/config.toml):

[mcp_servers.bitbucket-mcp]
command = "uvx"
args = ["--from", "bitbucket-mcp-py", "bitbucket-mcp"]
env = { BITBUCKET_USERNAME = "[email protected]", BITBUCKET_TOKEN = "your-api-token", BITBUCKET_WORKSPACE = "your-workspace" }

Note: The PyPI package is bitbucket-mcp-py but the command entry point is bitbucket-mcp. The --from flag is required with uvx.

Quick Commands

# Container management (uses podman or docker automatically)
make build          # Build container image
make up             # Start container
make down           # Stop container
make verify         # Test Bitbucket authentication
make test           # Run tests locally
make logs           # Show container logs
make clean          # Remove container and image

# Execute MCP server
podman exec -i bitbucket-mcp python -m src.main --transport stdio

Project Structure

src/
├── main.py              # CLI entry point (stdio/HTTP transport)
├── server.py            # MCP server, tool registration
├── client.py            # BitbucketClient (async, Basic Auth)
└── utils/
    ├── credentials.py   # Secure credentials (env vars + keychain)
    ├── pagination.py    # Pagination utilities (max_pages, max_items)
    └── transformers.py  # Slim response transformers (reduce LLM token usage)

configs/
└── tools.json           # Tool enable/disable configuration

.github/workflows/
├── ci.yml               # CI pipeline (tests, chart lint, image smoke test, chart publish check, build)
└── release.yml          # Release pipeline (PyPI + MCP Registry + GHCR image + Helm chart + GitHub Release)

charts/bitbucket-mcp/    # Helm chart (multi-tenant HTTP); examples/k3s-traefik.yaml, examples/gke.yaml

docs/
├── deployment-kubernetes.md  # Kubernetes deployment guide
└── deployment-modes.md       # Deployment modes and threat model (stdio, HTTP single/multi-tenant)

tests/                   # pytest test suite (incl. tests/test_helm_chart.py)
scripts/                 # Shell scripts (build.sh, run.sh)
server.json              # MCP Registry server manifest