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