Bitbucket MCP Server

Servidor MCP (Model Context Protocol) para Bitbucket Cloud que expone operaciones de Pull Requests como herramientas para Claude y otros clientes MCP.

Requisitos previos

• Node.js >= 18
• Una cuenta de Bitbucket Cloud
• Un API Token de Bitbucket con permisos de lectura/escritura en Pull Requests

Crear un API Token

Nota: Los App Passwords de Bitbucket estan deprecados. Desde septiembre 2025 no se pueden crear nuevos y en junio 2026 dejaran de funcionar. Usar API Tokens en su lugar.

1. Ir a Atlassian API Tokens
2. Click en Create token
3. Asignar permisos: Pull requests: Read & Write, Repositories: Read
4. Copiar el token generado

Instalacion

git clone <repo-url>
cd bitbucket-mcp-server
npm install
npm run build

Configuracion

Copiar el archivo de ejemplo y completar con tus credenciales:

cp .env.example .env

BITBUCKET_USERNAME=tu-email@ejemplo.com
BITBUCKET_API_TOKEN=tu-api-token
BITBUCKET_WORKSPACE=tu-workspace

Variables de entorno

| Variable | Requerida | Default | Descripcion | |---|---|---|---| | BITBUCKET_USERNAME | Si | - | Email o username de Bitbucket | | BITBUCKET_API_TOKEN | Si | - | API Token de Bitbucket | | BITBUCKET_WORKSPACE | No | - | Workspace por defecto (evita pasarlo en cada llamada) | | BITBUCKET_ENABLE_DANGEROUS | No | false | Habilita operaciones destructivas (merge, decline) | | TRANSPORT | No | stdio | Modo de transporte: stdio o http | | PORT | No | 3000 | Puerto HTTP (solo si TRANSPORT=http) |

Uso como MCP local

Importante: node vs nvm

Los clientes MCP lanzan el servidor como un proceso hijo usando el command configurado. Esto significa que el binario de node debe ser accesible desde la ruta indicada.

• Si instalaste Node.js directamente (instalador, Homebrew, etc.), node esta disponible globalmente y podes usarlo directamente como command.
• Si usas nvm, el binario de node no esta en una ruta fija global sino dentro de ~/.nvm/versions/node/vXX.X.X/bin/node. Algunos clientes MCP (como Claude Desktop) no cargan el perfil de tu shell, por lo que node no se encuentra.

Solucion para usuarios de nvm: usar la ruta absoluta al binario de node. Para obtenerla:

# Ver la ruta al node activo
which node
# Ejemplo de salida: /Users/tu-usuario/.nvm/versions/node/v22.0.0/bin/node

Y usar esa ruta completa en el campo command de la configuracion:

{
  "command": "/Users/tu-usuario/.nvm/versions/node/v22.0.0/bin/node"
}

Nota: Si actualizas la version de Node con nvm, vas a tener que actualizar esta ruta tambien.

---

Claude Code

Claude Code soporta tres scopes al registrar un MCP server con claude mcp add:

| Scope | Flag | Donde se guarda | Disponibilidad | |---|---|---|---| | local | (default) | Config interna del proyecto actual (~/.claude.json -> projects.<path>.mcpServers) | Solo para vos, en el proyecto actual | | project | -s project | .mcp.json en la raiz del repo | Compartido con el equipo via control de versiones | | user | -s user | ~/.claude.json (clave mcpServers a nivel raiz) | Para tu usuario, en todos los proyectos de tu maquina |

Importante: los MCP servers no se configuran en ~/.claude/settings.json ni en .claude/settings.json. Esos archivos son para configuracion general (modelo, hooks, permisos). Las versiones actuales de Claude Code leen MCP servers solo desde ~/.claude.json (scopes local y user) y .mcp.json (scope project).

Instalacion global (recomendado)

Para que el MCP este disponible en todos tus proyectos, usar el scope user:

claude mcp add bitbucket -s user -- node /ruta/absoluta/a/bitbucket-mcp-server/dist/index.js

Tambien podes pasar las variables de entorno en el mismo comando:

claude mcp add bitbucket -s user \
  -e BITBUCKET_USERNAME=tu-email@ejemplo.com \
  -e BITBUCKET_API_TOKEN=tu-api-token \
  -e BITBUCKET_WORKSPACE=tu-workspace \
  -- node /ruta/absoluta/a/bitbucket-mcp-server/dist/index.js

Verificar que quedo registrado:

claude mcp list

Para removerlo en el futuro:

claude mcp remove bitbucket -s user

Instalacion por proyecto

Si solo lo queres para el proyecto actual, omitir -s user (scope local por defecto) o usar -s project para compartirlo con el equipo via .mcp.json:

# Solo para vos en este proyecto
claude mcp add bitbucket -- node /ruta/absoluta/a/bitbucket-mcp-server/dist/index.js

# Compartido con el equipo (genera .mcp.json en la raiz del repo)
claude mcp add bitbucket -s project -- node /ruta/absoluta/a/bitbucket-mcp-server/dist/index.js

Configuracion manual

Tambien podes editar directamente el archivo correspondiente al scope deseado:

• Scope user (global): ~/.claude.json — agregar el server dentro de la clave mcpServers a nivel raiz del JSON.
• Scope project: .mcp.json en la raiz del repo (commiteable).

Estructura del bloque a agregar en cualquiera de los dos casos:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/ruta/absoluta/a/bitbucket-mcp-server/dist/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "tu-email@ejemplo.com",
        "BITBUCKET_API_TOKEN": "tu-api-token",
        "BITBUCKET_WORKSPACE": "tu-workspace"
      }
    }
  }
}

Si usas nvm, reemplazar "node" por la ruta absoluta (ver seccion anterior).

Claude Desktop

Agregar en ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/ruta/absoluta/a/bitbucket-mcp-server/dist/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "tu-email@ejemplo.com",
        "BITBUCKET_API_TOKEN": "tu-api-token",
        "BITBUCKET_WORKSPACE": "tu-workspace"
      }
    }
  }
}

Si usas nvm, reemplazar "node" por la ruta absoluta (ver seccion "node vs nvm"). Claude Desktop no carga el perfil de shell, por lo que nvm no estara disponible.

Cursor / Windsurf / otros editores

La configuracion es similar. Buscar la seccion de MCP servers en la configuracion del editor y agregar:

• Command: node (o ruta absoluta si usas nvm)
• Args: ["/ruta/absoluta/a/bitbucket-mcp-server/dist/index.js"]
• Env: las variables de entorno listadas arriba

Modo HTTP (alternativo)

Si se necesita un servidor HTTP en lugar de stdio:

TRANSPORT=http PORT=3000 npm start

Endpoints disponibles:

• POST /mcp - Recibe requests MCP
• GET /health - Health check

Herramientas disponibles

Lectura

| Herramienta | Descripcion | |---|---| | list_pull_requests | Lista PRs de un repositorio (filtrar por estado: OPEN, MERGED, DECLINED, SUPERSEDED) | | get_pull_request | Detalle completo de un PR | | get_pull_request_diff | Diff en formato unificado | | get_pull_request_comments | Comentarios del PR (generales e inline) | | get_pull_request_activity | Log de actividad (cambios de estado, aprobaciones, comentarios) |

Escritura

| Herramienta | Descripcion | |---|---| | create_pull_request | Crear un nuevo PR | | update_pull_request | Actualizar titulo, descripcion o reviewers | | approve_pull_request | Aprobar un PR | | unapprove_pull_request | Quitar aprobacion | | request_changes | Solicitar cambios | | add_pull_request_comment | Agregar comentarios (generales, inline en lineas, o respuestas) |

Operaciones peligrosas (requieren BITBUCKET_ENABLE_DANGEROUS=true)

| Herramienta | Descripcion | |---|---| | merge_pull_request | Mergear un PR (estrategias: merge_commit, squash, fast_forward) | | decline_pull_request | Rechazar un PR |

Desarrollo

# Compilar en modo watch
npm run dev

# En otra terminal, probar el servidor
npm start