mcp-bitbucket

Bitbucket Server para agentes de IA y los humanos que están a su lado. Lee pull requests y sus diffs sin clonar, redacta una revisión y publícala con un veredicto, publica tareas bloqueantes, explora código y commits, abre, fusiona o rechaza pull requests — desde un cliente MCP, desde una shell, o desde tu propio TypeScript.

Solo Bitbucket Server / Data Center. Bitbucket Cloud no es compatible.

Paquetes

Uso de herramientas de Claude Code / Claude Desktop → mcp. Terminal, scripts, CI, agentes que ejecutan comandos → cli. Si construyes algo más → core. Leen las mismas credenciales y se instalan lado a lado.

Related MCP server: Atlassian Bitbucket MCP Server

Requisitos previos

• Node.js 18+, pnpm 10+ (corepack enable)

• Un token de acceso personal de Bitbucket Server — perfil → Manage Account → HTTP Access Tokens, con lectura de repositorio y escritura de pull requests

• Solo para bb login (llavero del sistema): sudo apt install -y libsecret-1-0 gnome-keyring. Todos los comandos también funcionan con BITBUCKET_TOKEN.

Instalación

pnpm install
pnpm build        # core first, then mcp and cli

Puntos de entrada: packages/mcp/dist/index.js, packages/cli/dist/index.js.

Inicio rápido

Servidor MCP

claude mcp add mcp-bitbucket \
  -e BITBUCKET_URL=https://bitbucket.example.com \
  -e BITBUCKET_TOKEN=your-personal-access-token \
  -- node /absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js

O en .mcp.json (${VAR} es expandido por Claude Code, así que no se compromete ningún secreto):

{
  "mcpServers": {
    "mcp-bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "${BITBUCKET_URL}",
        "BITBUCKET_TOKEN": "${BITBUCKET_TOKEN}"
      }
    }
  }
}

Transporte HTTP en lugar de stdio: node packages/mcp/dist/index.js --http (puerto 3000) o MCP_HTTP_PORT=8080 node …. Rutas: POST /mcp, GET /mcp (SSE), DELETE /mcp.

CLI bb

pnpm --filter @mcp-bitbucket/cli link --global
bb login          # or export BITBUCKET_URL / BITBUCKET_TOKEN
bb whoami         # proves authentication — `bb ping` only proves reachability
bb pr get 42      # repository comes from the git origin remote

Superficie de comandos: packages/cli/README.md o bb --help.

Habilidad de Claude Code

bash packages/skill/scripts/install.sh            # ~/.claude/skills/bitbucket-review
bash packages/skill/scripts/install.sh ./.claude  # project scope

Necesita bb en PATH y una credencial resoluble.

Configuración

Variables de entorno, .env en la raíz del repositorio se carga automáticamente (cp .env.example .env). El servidor MCP las valida al inicio; el CLI también acepta --url / --token, que tienen prioridad sobre todo.

Límites

Cada tope numérico vive en packages/core/src/operations/caps.ts y se puede sobrescribir con variables de entorno: BITBUCKET_DIFF_MAX_CHARS (60000), BITBUCKET_DIFF_HEAD_RATIO (0.6), BITBUCKET_DIFF_CONTEXT_LINES (3), BITBUCKET_DIFF_FETCH_MAX_CHARS (12000000), BITBUCKET_DIFF_CACHE_ENTRIES (4), BITBUCKET_CHANGED_FILES_MAX_ITEMS (1000), BITBUCKET_CHANGED_FILES_STATS_MAX_FILES (500). La truncación nunca es silenciosa: la nota nombra el parámetro y la variable que elevan el tope, y lista cada encabezado de hunk omitido.

Permisos

Dos guardas independientes.

MCP_PERMISSION_MODE — solo servidor MCP. Cada herramienta se clasifica como read, write o destructive en packages/mcp/src/permissions.ts; una herramienta prohibida se oculta de ListTools y se rechaza cuando se llama por nombre.

El CLI no lo lee. Una implementación readonly no detiene bb review merge.

Lista blanca de repositorios — ambos puntos de entrada. BITBUCKET_ALLOWED_PROJECTS / BITBUCKET_ALLOWED_REPOS aceptan patrones separados por comas, punto y coma o espacios: PROJ, PROJ/*, PROJ/repo-a. La comprobación se ejecuta dentro del cliente compartido antes de que se abra cualquier socket, por lo que todas las herramientas y todos los comandos bb la heredan. Sin definir significa todos los repositorios. No distingue mayúsculas; los repositorios personales son el proyecto ~username. Un patrón malformado se descarta, nunca se amplía — un valor compuesto solo de patrones malformados no permite nada.

Herramientas

29 herramientas MCP: 17 de lectura, 9 de escritura, 3 destructivas. Parámetros completos en docs/tools.md.

Valores predeterminados notables

• La discusión resuelta está oculta. get_pull_request_comments / bb comment ls necesitan includeResolved (--include-resolved) para mostrar hilos y tareas resueltos; la respuesta indica cuántos ocultó. Un filtro state explícito anula el valor predeterminado.

• Las revisiones se redactan, no se publican. add_pr_draft_comment / bb review draft almacenan un comentario invisible; submit_pr_review publica todos los comentarios pendientes con un veredicto como una sola notificación. pending: false (--no-pending) publica inmediatamente; discard_pr_draft_review descarta el borrador.

• bb ping ≠ autenticación. /application-properties responde 200 de forma anónima en muchas instancias. bb whoami es la comprobación de autenticación.

Desarrollo

pnpm build | typecheck | test | lint | format | clean
pnpm dev:mcp                 # MCP server from source (tsx)
pnpm cli pr ls               # bb from source
pnpm --filter @mcp-bitbucket/core test

La regla de capas que evita que los adaptadores se desvíen:

• core no sabe nada de MCP ni del CLI — sin SDK de MCP, sin yargs, sin stdout. Las operaciones toman un cliente más parámetros y devuelven datos estructurados o lanzan una excepción.

• Los adaptadores son dueños de la validación de entrada y la forma de salida — zod más la forma de resultado de MCP en mcp, yargs más texto/--json en cli. Ninguno se filtra a core.

• Los mensajes de error se escriben una vez, en core, con marcadores de posición estilo {projects} / {login} que cada adaptador renderiza en su propio vocabulario — el mismo fallo dice "usa list_projects" a un modelo y "usa bb project ls" a ti.

• Una nueva capacidad es una operación más un formateador en core, luego un adaptador fino en cada uno de mcp y cli.

Docker

La imagen lleva solo el servidor MCP.

docker build -t mcp-bitbucket .
docker run -i --rm -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… mcp-bitbucket
docker run --rm -p 3000:3000 -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… -e MCP_HTTP_PORT=3000 mcp-bitbucket

Solución de problemas

docs/troubleshooting.md. Los tres más comunes: una herramienta que falta en la lista del cliente significa que MCP_PERMISSION_MODE la ocultó (un valor no reconocido oculta las 29); Refused: … outside the configured repository allowlist significa que la lista blanca no cubre ese repositorio; menos comentarios que en la interfaz web significa que los hilos resueltos están ocultos.

Limitaciones

• Solo Bitbucket Server; sin Bitbucket Cloud, sin OAuth/SSO ni contraseñas de aplicación.

• bb login almacena credenciales solo en el llavero del sistema — sin almacenamiento en texto plano, sin --password.

• Sin webhooks ni modo dirigido por eventos; el servidor responde a llamadas de herramientas.

• Los diffs son texto de diff unificado renderizado por el servidor; los comentarios en línea anclados al diff no se exponen.

• search_code necesita el índice de código de la instancia: rama predeterminada, palabras completas, sin expresiones regulares.

• MCP_PERMISSION_MODE controla solo el servidor MCP; la lista blanca controla ambos.