bitbucket-mcp

Servidor MCP para Bitbucket Cloud. Pull requests, revisión de código, ramas, código fuente, pipelines, webhooks y variables, expuestos como una superficie de herramientas controlada en lugar de llamadas REST en crudo.

Por qué existe

El MCP oficial de Atlassian solo cubre Jira y Confluence. Bitbucket queda fuera, así que cada operación de repositorio termina recurriendo a llamadas REST escritas a mano: payloads verbosos, sin salvaguardas, y un token que puede alcanzar cualquier cosa que el alcance permita.

Este servidor cierra esa brecha en tres frentes:

• Payloads recortados. Las respuestas se normalizan hasta quedarse con los campos que realmente usas, de modo que revisar una PR cuesta una fracción del contexto que consumiría una respuesta REST cruda.

• Salvaguardas en el servidor, no en el prompt. Las ramas protegidas, el confirm en acciones destructivas y un modo de solo lectura se aplican antes de que la llamada HTTP salga.

• Una herramienta por intención. 55 herramientas que cubren los flujos de revisión, ramas, pipelines y webhooks, en lugar de una vía de escape HTTP genérica.

flowchart LR
  A["MCP client<br/>(Claude Code, Inspector)"] -->|stdio| B["bitbucket-mcp"]
  B --> C{"Guards"}
  C -->|"read only, confirm,<br/>protected branch,<br/>workspace lock"| D["Bitbucket Cloud<br/>REST API"]
  C -.->|refused before<br/>the HTTP call| A
  B --> E["git over SSH<br/>or HTTPS"]
  E --> F["Repository"]
  D -->|normalized,<br/>trimmed response| A

Related MCP server: mcp-server-atlassian-bitbucket

Instalación

El paquete se publica en npm como @marcusyoda/bitbucket-mcp.

Requisitos

• Node >= 20

• Un token de API de Atlassian con ámbito (consulta Autenticación)

• Una clave SSH registrada en Bitbucket, para las herramientas git_* por SSH. Opcional si usas las variantes HTTPS en su lugar.

Opción 1: npx, sin instalar nada

La vía más rápida. Apunta tu cliente MCP al paquete y deja que npx lo resuelva:

npx -y @marcusyoda/bitbucket-mcp

Opción 2: instalación global

npm install -g @marcusyoda/bitbucket-mcp
# or: pnpm add -g @marcusyoda/bitbucket-mcp
bitbucket-mcp

Opción 3: desde el código fuente

git clone https://github.com/marcusyoda/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install
pnpm build          # dist/index.js

Registro en tu cliente MCP

Claude Code, mediante CLI

claude mcp add bitbucket \
  --env BITBUCKET_EMAIL=you@example.com \
  --env BITBUCKET_API_TOKEN=your-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- npx -y @marcusyoda/bitbucket-mcp

Cualquier cliente, mediante .mcp.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@marcusyoda/bitbucket-mcp"],
      "env": {
        "BITBUCKET_EMAIL": "you@example.com",
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_DEFAULT_REPO": "your-repo-optional"
      }
    }
  }
}

¿Ejecutas desde el código fuente? Sustituye el comando por el punto de entrada compilado:

{ "command": "node", "args": ["/abs/path/to/bitbucket-mcp/dist/index.js"] }

Verifica la conexión llamando a get_current_user: hace un viaje de ida y vuelta con el token y devuelve tu identidad de Bitbucket.

Autenticación

La autenticación es HTTP Basic con email:api_token. Crea un token de API con ámbito en id.atlassian.com > Manage account > Security > API tokens.

Ámbitos del token (selector granular, crea solo lo que uses):

Las herramientas de variables (*_variable*, list_deployment_*) necesitan admin:repository:bitbucket. Omitir ese ámbito no es problema: esas herramientas devuelven un 403 y todo lo demás sigue funcionando.

La justificación y el registro completo de decisiones sobre permisos están en PERMISSIONS.md.

Entorno

Copia .env.example a .env para ejecuciones locales. Nunca lo incluyas en un commit.

El .env del paquete se carga solo cuando BITBUCKET_API_TOKEN no está presente en el entorno. De ese modo, un lanzador que inyecte credenciales por proyecto siempre prevalece, y un .env suelto de otro workspace nunca puede sobrescribir el token inyectado.

Modelo de seguridad

• BITBUCKET_READ_ONLY=true bloquea toda herramienta de escritura o destructiva antes de que llegue a la API.

• Las herramientas destructivas (merge, decline, delete_*, stop_pipeline, git_commit, git_push, comentarios inline en PR) requieren confirm: true.

• Crear una variable secured también requiere confirm: true.

• Los valores de las variables secured son de solo escritura en la API y nunca se devuelven ni se registran.

• Ramas protegidas (BITBUCKET_PROTECTED_BRANCHES, por defecto main,dev) están bloqueadas por completo contra la mutación directa: git_push, git_rebase (cuando está activa), delete_branch y create_branch se niegan a apuntar a ellas, incluso con confirm. Introduce los cambios allí mediante una PR: merge_pull_request sobre una rama protegida está permitido con confirm: true.

• Bloqueo de workspace. Con BITBUCKET_LOCK_WORKSPACE=true, se rechaza cualquier llamada que nombre un workspace distinto. Pensado para máquinas que atienden a varios clientes desde una sola instalación.

Herramientas

Todas las herramientas aceptan workspace y repo opcionales para sobrescribir los valores por defecto del entorno.

Repositorio y metadatos: get_current_user, list_repositories, get_repository, create_repository

Pull requests: list_pull_requests, get_pull_request, get_pull_request_diff, get_pull_request_activity, create_pull_request, update_pull_request, approve_pull_request, unapprove_pull_request, request_changes_pull_request, decline_pull_request (confirm), merge_pull_request (confirm), list_pr_commits, get_diff

Comentarios: list_pr_comments, add_pr_comment (inline requiere confirm), reply_pr_comment, update_pr_comment, delete_pr_comment (confirm), resolve_comment, react_pr_comment (experimental)

Ramas, código fuente y git: list_branches, get_branch, create_branch, delete_branch (confirm), get_file_source, list_directory, clone_repo, clone_repo_https, git_commit (confirm), git_rebase, git_push (confirm), git_push_https (confirm). Todas las herramientas de push y de ramas rechazan las ramas protegidas.

Pipelines: list_pipelines, get_pipeline, get_pipeline_steps, get_pipeline_step_log, trigger_pipeline, stop_pipeline (confirm)

Variables: list_repo_pipeline_variables, upsert_repo_pipeline_variable, delete_repo_pipeline_variable (confirm), list_workspace_variables, list_deployment_environments, list_deployment_variables, upsert_deployment_variable, delete_deployment_variable (confirm)

Webhooks: list_webhooks, get_webhook, create_webhook, update_webhook, delete_webhook (confirm)

SSH o HTTPS para git

clone_repo, git_commit, git_rebase y git_push usan tu clave SSH, no el token. Cuando SSH no es una opción, clone_repo_https y git_push_https autentican con username:token y necesitan BITBUCKET_USERNAME. La salvaguarda de ramas protegidas se aplica a ambos transportes.

Limitaciones conocidas

• react_pr_comment es experimental. Las reacciones con emojis en los comentarios de PR están documentadas para Bitbucket Data Center, no para Cloud. La herramienta apunta a un endpoint de mejor esfuerzo y puede devolver un error si tu workspace no lo admite.

• resolve_comment depende de que la resolución de hilos de comentarios esté disponible para el repositorio.

• No existe un endpoint que liste qué variables espera un pipeline personalizado. Esa información viene de bitbucket-pipelines.yml, léela con get_file_source.

• Volver a leer los valores almacenados de las variables requiere el ámbito de administrador.

Desarrollo

pnpm install
pnpm dev         # tsx watch
pnpm typecheck
pnpm build       # tsup, ESM
pnpm inspect     # build and open the MCP Inspector

Las reglas y convenciones del proyecto están en CLAUDE.md. Las contribuciones siguen el flujo de trabajo "issue primero": cada commit enlaza un issue en su cabecera, con el formato type(scope): subject [#N].

Úsalo

Con licencia MIT, y esto es literal: úsalo en el trabajo, úsalo comercialmente, hazle fork, incorpóralo a tus propias herramientas, renómbralo. No hay que pedir permiso y no hay ningún ritual de atribución más allá de conservar el aviso de licencia. Si te ahorra una tarde escribiendo llamadas REST a mano, ya se ha pagado por sí mismo.

¿Te falta alguna herramienta o has encontrado un endpoint de Bitbucket que no cubre? Abre un issue. Las pull requests son bienvenidas: la única regla de la casa es que cada commit enlace un issue en su cabecera, con el formato type(scope): subject [#N].

Consulta LICENSE.