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

[email protected]
BITBUCKET_API_TOKEN=tu-api-token
BITBUCKET_WORKSPACE=tu-workspace

Variables de entorno

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:

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 [email protected] \
  -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": "[email protected]",
        "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": "[email protected]",
        "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

Escritura

Operaciones peligrosas (requieren BITBUCKET_ENABLE_DANGEROUS=true)

Desarrollo

# Compilar en modo watch
npm run dev

# En otra terminal, probar el servidor
npm start