Bitbucket

Servidor MCP de Bitbucket

Servidor MCP para Bitbucket, diseñado para agentes de codificación con IA que necesitan trabajar con repositorios remotos como si fueran clones locales: búsqueda de código tan rápida como grep, lecturas de archivos por ventanas, respuestas compactas y eficientes en tokens, y una capa de transporte que nunca dispara los límites de tasa de Bitbucket.

Compatible con Bitbucket Server / Data Center (objetivo principal) y Bitbucket Cloud.

Por qué v3

	v2	v3
Búsqueda de contenido en un repositorio	1 listado + hasta 3.000 GET de archivos	1 llamada de archivo en frío, 0–1 llamadas en caliente
Integridad de la búsqueda	silenciosamente parcial bajo limitación del servidor	completa, con cada límite reportado
Tokens de diff de PR	JSON por línea (~4× más grande)	diff unificado en bruto
Leer una ventana de 100 líneas	2 llamadas, archivo completo transferido	1 llamada, solo la ventana
Blame de una ventana de un archivo enorme	hasta 100 llamadas	1 llamada
Seguridad frente a límites de tasa	ninguna (ráfaga → 429/403)	ritmo del lado del cliente ajustado al limitador de DC
Herramientas	33	25 (~30% menos contexto de definición)

Medido en una instancia real de Data Center: una búsqueda de contenido repetida pasó de 519 llamadas API / ~7s (encontrando 1 de 8 coincidencias reales bajo limitación por ráfagas) a 0 llamadas API / 24ms encontrando las 8. Diseño completo e investigación de API verificada: REVAMP_PLAN.md.

Herramientas (25)

Búsqueda (search) — solo Server/DC

• grep — busca contenidos de archivos con regex completo, en cualquier rama, como ripgrep en un clon local. Una descarga de archive por repositorio+commit, transmitida en memoria constante, cacheada en proceso, con verificación de frescura en cada llamada (las respuestas incluyen as_of <commit>). Omite query para un listado de globs solo por nombre de archivo. Modos: content, files, count; glob, path, context, case_insensitive, max_results.
• search_code — búsqueda de términos exactos respaldada por índice en un proyecto entero en una sola llamada (solo rama predeterminada, insensible a mayúsculas, sin regex, archivos <512 KiB, ventana de ~1000 resultados). Ideal para búsquedas de identificadores entre repositorios; usa grep para todo lo demás.
• search_repositories — encuentra repositorios por nombre/descripción.

Pull requests (pr_core)

• get_pull_request — metadatos + estado de revisores + información de fusión en 1 llamada; include_comments / include_file_changes (predeterminado true), include_tasks, comment_limit. Devuelve version para mutaciones posteriores.
• list_pull_requests — limitado al repositorio; omite repository (Server) para tus PR en todos los repositorios en una sola llamada (filtro role).
• create_pull_request, update_pull_request, merge_pull_request, decline_pull_request — todas las mutaciones aceptan version de una lectura previa (ahorra una búsqueda; re-búsqueda automática + reintento una vez en conflictos 409).

Comentarios y tareas (pr_comments)

• add_comment — general, respuesta en hilo, en línea (file_path + line_number, o auto-resolución con code_snippet), código suggestion, o tarea (severity: "BLOCKER", Server). Los adjuntos se suben mediante el parámetro attachments (Server).
• manage_comment — edit / delete / resolve / reopen / to_task / to_comment en cualquier comentario o tarea, en una sola llamada con version.

Revisión (pr_review)

• get_pull_request_diff — texto de diff unificado en bruto; delimita con file_path (del lado del servidor), include_patterns/exclude_patterns, context_lines, ignore_whitespace.
• set_review_status — APPROVED / NEEDS_WORK / UNAPPROVED (mutuamente excluyentes; una sola llamada).

Commits (commits)

• list_pr_commits, list_branch_commits (filtros since-rev/merges del lado del servidor; recorrido de páginas acotado para author/until/search del lado del cliente), get_commit_detail (diff unificado, o detail: "files" para la lista de archivos modificados sin cuerpos).

Ramas (branches)

• list_branches, get_branch (rama + sus PR), delete_branch (expected_head omite la llamada de búsqueda).

Archivos (files)

• get_file_content — ventanas del lado del servidor: start_line/line_count transfieren solo esa ventana (≤5000 líneas/llamada). full_content / start_line negativo para lecturas de archivo completo o de cola.
• get_file_blame — blame de rango de commits para una ventana de líneas en 1 llamada (Server).
• list_directory_content — paginado y compacto.

Adjuntos (attachments, Server) / Descubrimiento (discovery)

• manage_attachments (download limitado, delete), list_projects, list_repositories.

Convenciones de salida

• El contenido masivo (diffs, archivos, resultados de grep) es texto plano, no cadenas con escape JSON; las listas son JSON compacto sin formato bonito. Las fechas son ISO-8601.
• Las respuestas derivadas de contenido incluyen as_of <commit> para que el agente sepa exactamente qué estado vio.
• La truncación nunca es silenciosa — cada límite produce una advertencia explícita con orientación de continuación (next_start, "reduce el glob", etc.).
• Las entidades mutables incluyen version, para que las mutaciones no necesiten una re-lectura.

Instalación

Usando npx (recomendado)

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@nexus2520/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_USERNAME": "your.username",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Para Bitbucket Cloud usa BITBUCKET_APP_PASSWORD en lugar de BITBUCKET_TOKEN (y omite BITBUCKET_BASE_URL).

Guías de credenciales: Contraseña de aplicación de Cloud · Token HTTP de Server/DC.

Desde el código fuente

git clone https://github.com/pdogra1299/bitbucket-mcp-server.git
cd bitbucket-mcp-server
npm install && npm run build
# point your MCP config at: node <repo>/build/index.js

Configuración

Cada política numérica es ajustable por entorno — nada está codificado de forma fija. La tabla completa está en src/config/index.ts (CONFIG_REFERENCE). Las más importantes:

Variable	Predeterminado	Propósito
BITBUCKET_RATE_LIMIT_RPS	5	Tasa sostenida de solicitudes del lado del cliente (la recarga por usuario de DC es 5/s). 0 desactiva el ritmo — configúralo si tu cuenta tiene exención de límite de tasa de administrador
BITBUCKET_RATE_LIMIT_BURST	50	Capacidad de ráfaga (el bucket del servidor de DC es 60)
BITBUCKET_GLOBAL_MAX_CONCURRENCY	8	Máximo de solicitudes en vuelo entre todas las herramientas
BITBUCKET_SNAPSHOT_MAX_MB	256	Presupuesto de caché de grep en memoria. 0 = transmisión pura (sin retención, aún 2 llamadas por búsqueda)
BITBUCKET_SNAPSHOT_MAX_FILE_KB	2048	Los archivos más grandes que esto se escanean pero no se cachean
BITBUCKET_REF_RESOLVE_TTL_MS	15000	Memo de frescura rama→SHA; 0 = validar en cada llamada individual
BITBUCKET_STREAM_ABORT_MB	2048	Aborta escaneos de archivo después de tantos MB extraídos (vuelve a escaneo de archivo por archivo acotado)
BITBUCKET_HTTP_TIMEOUT_MS	30000	Tiempo de espera por solicitud
BITBUCKET_TOOL_GROUPS	all	Grupos separados por comas para exponer (validados, aplicados en el despacho, cierre seguro ante fallo)

Las garantías del motor de grep

• Memoria acotada: el archivo se transmite, nunca se almacena completo en búfer; la caché es un presupuesto de bytes estricto con evicción LRU y deduplicación por hash de contenido entre ramas. Peor caso = presupuesto + unos pocos MB transitorios.
• Frescura: cada consulta vuelve a resolver el head de la rama; una rama movida nunca puede servir resultados obsoletos. Las fusiones/eliminaciones hechas a través de este servidor invalidan inmediatamente.
• Completitud: los límites de caché nunca reducen la cobertura del escaneo — los archivos sobredimensionados aún se escanean; solo se omiten los binarios reales, y se cuentan en la salida.

Límites de tasa

Todas las solicitudes pasan por un bucket de tokens ajustado al limitador por usuario de Bitbucket DC, por lo que los errores 429 se evitan en lugar de reintentarse después. Si tu instancia limita fuertemente de todos modos, el mensaje de error dice exactamente qué hacer — la solución duradera es pedir a un administrador de Bitbucket una exención de límite de tasa para la cuenta de servicio (Administración → Límites de tasa → Exenciones) y luego configurar BITBUCKET_RATE_LIMIT_RPS=0.

Migración desde v2

Herramientas eliminadas y sus equivalentes en v3 (mismas capacidades, menos herramientas):

v2	v3
find_in_files	grep con query
search_files	grep sin query (usa glob)
list_pr_tasks	get_pull_request + include_tasks: true
create_pr_task	add_comment + severity: "BLOCKER"
update_pr_task	manage_comment action: "edit"
delete_pr_task, delete_comment	manage_comment action: "delete"
set_pr_task_status	manage_comment action: "resolve" / "reopen"
convert_pr_item	manage_comment action: "to_task" / "to_comment"
set_pr_approval	set_review_status status: "APPROVED" / "UNAPPROVED"

Actualiza las listas de permisos de Claude Code (mcp__bitbucket__*) en consecuencia. Las herramientas de diff ahora devuelven texto de diff unificado en lugar de JSON por línea — los números de línea provienen de los encabezados @@. Detalles completos en CHANGELOG.md.

Desarrollo

npm run build   # tsc → build/
npm test        # build + node --test (unit + snapshot-engine tests)

Arquitectura: src/config (toda la política) · src/core (transporte, motor de instantáneas, cachés) · src/handlers (lógica de herramientas) · src/tools (definiciones, guardias, registro) · src/formatting (salida compacta) · src/types (barril único).

Licencia

MIT