Servidor MCP de Bitbucket (Python)

Conecta Claude Code, OpenAI Codex, Cursor, VS Code (GitHub Copilot) y cualquier asistente de IA compatible con MCP a tus repositorios de Bitbucket Cloud. Revisa solicitudes de extracción, monitorea pipelines y gestiona tu código — todo mediante lenguaje natural.

Funcionalidades

• Más de 60 herramientas MCP — repositorios, solicitudes de extracción, comentarios, tareas, diferencias, pipelines (en tiempo de ejecución + configuración), estados de compilación, revisores, borradores de PR, revisión por lotes, sistema de seguimiento de incidencias, commits, exploración de archivos/código fuente

• Anotaciones de herramientas MCP 2025 — cada herramienta anuncia readOnlyHint / destructiveHint / idempotentHint / openWorldHint + un título legible, por lo que los clientes (Claude Code, Cursor) incluyen automáticamente herramientas de solo lectura y advierten antes de operaciones destructivas

• Respuestas ligeras — ruido de API eliminado para reducir el uso de tokens LLM

• Configurable — activa/desactiva herramientas mediante configs/tools.json o la variable de entorno BITBUCKET_TOOLS_CONFIG

• Credenciales seguras — variables de entorno o llavero del sistema

Related MCP server: Bitbucket MCP

Inicio rápido

1. Instalación

La forma recomendada de ejecutar el servidor es mediante uvx (instalación cero, entorno aislado):

# Always latest version
uvx --from bitbucket-mcp-py bitbucket-mcp

# Pin a specific version
uvx --from bitbucket-mcp-py==1.8.1 bitbucket-mcp

¿Por qué --from? El paquete en PyPI es bitbucket-mcp-py pero el punto de entrada del comando es bitbucket-mcp. La bandera --from le indica a uvx qué paquete instalar.

2. Configurar credenciales

Define las siguientes variables de entorno (o usa un archivo .env — consulta Credenciales):

Obtén tu token de API en: https://id.atlassian.com/manage-profile/security/api-tokens

⚠️ Usa un token con alcance, no uno global. Al crear el token, selecciona alcances específicos (ej. Repositories: Read, Pull requests: Read/Write). Los tokens globales sin alcances explícitos no funcionan con este servidor MCP.

3. Configurar tu asistente de IA

Claude Code (recomendado)

Opción A — CLI (la más rápida):

claude mcp add bitbucket-mcp \
  -e BITBUCKET_USERNAME=your-email@example.com \
  -e BITBUCKET_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

Opción B — Configuración JSON (~/.claude.json o .mcp.json del proyecto):

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

OpenAI Codex

Opción A — CLI (la más rápida):

codex mcp add bitbucket-mcp \
  --env BITBUCKET_USERNAME=your-email@example.com \
  --env BITBUCKET_TOKEN=your-api-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- uvx --from bitbucket-mcp-py bitbucket-mcp

Opción B — Configuración TOML (~/.codex/config.toml):

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

Cursor

Agrega a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

VS Code (GitHub Copilot)

Agrega a .vscode/mcp.json (del espacio de trabajo) o ~/Library/Application Support/Code/User/mcp.json (global, macOS):

{
  "servers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Herramientas disponibles

Deshabilitado por defecto: merge_pull_request (seguridad), stop_pipeline (seguridad), get_pull_request_patch (formato git am — no útil para revisión de IA), convert_pull_request_to_draft (no compatible con la API de Bitbucket), delete_issue (seguridad), delete_issue_comment (seguridad), add_commit_comment (operación de escritura), create_pipeline_variable / update_pipeline_variable / delete_pipeline_variable (operaciones de escritura), create_pipeline_schedule / update_pipeline_schedule / delete_pipeline_schedule (operaciones de escritura), delete_pipeline_cache (seguridad), create_environment / delete_environment / create_deployment_variable / update_deployment_variable / delete_deployment_variable (operaciones de escritura), create_branch_restriction / update_branch_restriction / delete_branch_restriction (operaciones de escritura). Habilitar en configs/tools.json.

Ámbitos de gobernanza — Las herramientas de lectura de restricciones de rama necesitan el ámbito repository (repository:admin puede ser necesario según la configuración del repositorio); las herramientas de escritura necesitan repository:admin. Las herramientas de miembros/permisos del espacio de trabajo necesitan el ámbito account. El endpoint /members enumera usuarios sin un permiso por usuario (use list_workspace_permissions para roles).

Ámbitos de despliegues — las herramientas de lectura (list_environments, get_environment, list_deployments, get_deployment, list_deployment_variables) necesitan el ámbito deployment; las herramientas de escritura necesitan deployment:write. Bitbucket no tiene un filtro del lado del servidor para despliegues por entorno (BCLOUD-18729) — filtre en el campo environment de list_deployments en su lugar. No existe la herramienta update_environment: Bitbucket no expone un PUT para entornos (solo POST .../changes para bloqueo).

Configuración de herramientas personalizadas

Por defecto, el servidor lee configs/tools.json incluido con el paquete. Puede apuntar a un archivo personalizado en tiempo de ejecución sin reconstruir:

export BITBUCKET_TOOLS_CONFIG=/path/to/my-tools.json

Cadena de respaldo (la primera coincidencia gana):

1. Variable de entorno BITBUCKET_TOOLS_CONFIG

2. configs/tools.json incorporado

Comportamiento a prueba de fallos — Si BITBUCKET_TOOLS_CONFIG está configurada pero el archivo falta o contiene JSON inválido, el servidor lanza un error al inicio (fallo explícito en lugar de ignorar silenciosamente la anulación). Si el valor predeterminado incorporado falta, todas las herramientas están habilitadas.

Consejo de tokens — get_pull_request_diff acepta un parámetro opcional path para filtrar el diff a un solo archivo, reduciendo el uso de tokens en ~95% en PRs grandes:

get_pull_request_diff(repo_slug, pull_request_id, path="src/services/myService.ts")

Consejo de tokens — get_pipeline_step_logs devuelve solo los últimos 100 KiB del registro de un paso por defecto (los registros sin procesar llegan a varios MB en pasos largos). La respuesta incluye un indicador truncated; amplíe la ventana con el rango absoluto de bytes start / end, o pase max_bytes=null para todo el registro. Pase un UUID de contenedor de servicio como log_uuid para leer el registro de ese servicio en lugar del contenedor de compilación. Este endpoint necesita un UUID de pipeline real — resuélvalo a través de get_pipeline_run si solo tiene un número de compilación.

get_pipeline_step_logs(repo_slug, pipeline_uuid="{adab6a1f-...}", step_uuid="{84fc6465-...}")

MCP Prompts

El servidor también expone MCP Prompts — plantillas parametrizadas que los clientes compatibles (Claude Code, Cursor, ...) muestran como comandos de barra. En lugar de recordar nombres de herramientas, invoca un prompt y el asistente orquesta las herramientas adecuadas para usted. Aparecen en el selector de prompts del cliente (prompts/list).

Los prompts se habilitan/deshabilitan en configs/tools.json bajo la clave prompts de nivel superior (separada de tools).

Credenciales

Opción 1: archivo .env (recomendada)

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

Opción 2: llavero del sistema (más seguro)

pip install 'bitbucket-mcp-py[keyring]'
python3 -c "import keyring; keyring.set_password('bitbucket-mcp', 'bitbucket_token', 'YOUR_TOKEN')"

Docker (Alternativa)

Si prefieres ejecutar el servidor en un contenedor:

docker build -t bitbucket-mcp-py .
docker run -d --name bitbucket-mcp --env-file .env bitbucket-mcp-py

Luego configura tu asistente de IA para usar docker exec:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "bitbucket-mcp", "python", "-m", "src.main", "--transport", "stdio"]
    }
  }
}

Transportes

El servidor habla stdio por defecto (el transporte estándar para clientes MCP locales). Para un despliegue en red también soporta Streamable HTTP (especificación MCP 2025-03-26):

# Streamable HTTP on 0.0.0.0:8080
python -m src.main --transport http --host 0.0.0.0 --port 8080

Los clientes se conectan a http://<host>:<port>/mcp (ej. http://localhost:8080/mcp).

--transport sse (Server-Sent Events heredado) aún se acepta pero está obsoleto — emite un DeprecationWarning. Prefiere --transport http.

HTTP sin estado (escalado horizontal / serverless)

--stateless ejecuta el transporte Streamable HTTP sin sesiones del lado del servidor: sin Mcp-Session-Id, un transporte nuevo por cada petición HTTP. Cualquier instancia detrás de un balanceador de carga puede atender cualquier petición — no se requieren sesiones persistentes.

python -m src.main --transport http --host 0.0.0.0 --port 8080 --stateless

⚠️ De un solo inquilino por defecto. Sin --multi-tenant el servidor atiende con su propio token de Bitbucket a nivel de proceso a todos los llamantes. Despliégalo en una red privada o detrás de un proxy inverso autenticado — o usa el modo multiinquilino, donde cada llamante trae sus propias credenciales.

--stateless requiere --transport http (se rechaza en stdio y en el sse heredado, cuyas aplicaciones ignoran el ajuste). También fuerza una respuesta JSON única en lugar de un flujo SSE, porque los entornos edge/serverless no pueden mantener abierta una respuesta en streaming — actualmente no hay forma de combinar stateless con streaming.

En ambos transportes HTTP se expone un endpoint de actividad para balanceadores de carga:

curl http://localhost:8080/healthz    # {"status": "ok"}

En un contenedor — el CMD por defecto de la imagen lo mantiene inactivo para uso mediante exec sobre stdio, por lo que el modo servidor se inicia sobrescribiendo el comando:

podman run -d --name bitbucket-mcp-http -p 8000:8000 --env-file .env bitbucket-mcp-py \
  python -m src.main --transport http --host 0.0.0.0 --port 8000 --stateless

Funciona igual con docker run. La imagen expone el puerto 8000.

Las dos listas de permitidos deben configurarse juntas: una lista de Host vacía rechaza toda petición (421), y una lista de Origin vacía rechaza todo cliente de navegador (403). Configurar solo una provoca un rechazo al inicio en lugar de bloquear silenciosamente el servidor.

export BITBUCKET_ALLOWED_HOSTS="mcp.example.com"
export BITBUCKET_ALLOWED_ORIGINS="https://app.example.com"

Sin ninguna de las dos listas, no se aplica protección contra rebote de DNS — adecuado para un servidor accesible a través de una red privada o un proxy de confianza. Establécelas tan pronto como el servidor esté expuesto en un nombre de host real.

HTTP multiinquilino (credenciales por petición)

Por defecto, un despliegue HTTP es de un solo inquilino: todos los llamantes actúan con el token de Bitbucket a nivel de proceso. --multi-tenant cambia eso — cada petición lleva el token de acceso OAuth de Bitbucket del propio llamante como Authorization: Bearer, y se ejecuta bajo esa identidad. El servidor no posee ninguna credencial de Bitbucket propia.

BITBUCKET_RESOURCE_SERVER_URL=https://mcp.example.com \
  python -m src.main --transport http --host 0.0.0.0 --port 8080 --stateless --multi-tenant

El token se verifica contra GET /2.0/user, que devuelve el account_id y el espacio de trabajo por defecto del llamante; el mismo token se reutiliza para las llamadas API posteriores, por lo que nunca se almacena ni mapea ninguna credencial. Las peticiones no autenticadas reciben un 401 con un desafío WWW-Authenticate que apunta a /.well-known/oauth-protected-resource.

Lo que esto aporta:

• Aislamiento — un cliente de Bitbucket por cada (identity, workspace); dos llamantes nunca comparten uno, y no hay token de proceso al que recurrir.

• workspace=None significa tu espacio de trabajo — se resuelve a partir de las membresías del llamante, nunca de BITBUCKET_WORKSPACE. Con cero o varias membresías no hay valor por defecto y las llamadas deben nombrar su espacio de trabajo.

• Registro de auditoría — cada llamada se registra en el logger bitbucket_mcp.audit con la herramienta, el account_id y el espacio de trabajo. Nunca las credenciales.

• Valores predeterminados más estrictos — las herramientas marcadas con destructiveHint se rechazan a menos que se habiliten explícitamente.

No compatible en este modo: Tokens de acceso a repositorio/espacio de trabajo de Bitbucket — no están vinculados a una cuenta de usuario, por lo que no se puede derivar una identidad. Usa HTTP de un solo inquilino para eso. Los tokens Bearer requieren TLS: termina HTTPS delante del servidor.

stdio no se ve afectado — sigue siendo de un solo usuario con variables de entorno, exactamente como se documentó anteriormente.

Consulta docs/deployment-modes.md para la matriz completa de los tres modos de despliegue y el modelo de amenazas de cada uno.

Desarrollo

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/test_client.py -v

Requisitos

• Python 3.12+

• Token de API de Bitbucket

Licencia

MIT

Referencias

• MCP Registry — Registro oficial de servidores MCP

• PyPI Package — Paquete Python

• MCP Python SDK

• Bitbucket API 2.0

• FastMCP Framework