Jenkins MCP server

¿Por qué jenkins-mcp-go?

La mayoría de las integraciones con Jenkins esperan a un humano frente al teclado. Los agentes LLM necesitan algo diferente: respuestas pequeñas y estructuradas; un camino claro desde "build fallido" hasta "aquí está la línea que falla"; y la capacidad de buscar en un registro de consola de varios gigabytes sin volver a descargarlo en cada pregunta.

jenkins-mcp-go está construido para ese flujo de trabajo:

• Lectura primero, escrituras opt-out. Las herramientas de lectura están siempre activas. Las herramientas de escritura (trigger_build, stop_build, cancel_queue_item) están controladas por JENKINS_MCP_READONLY: establece la variable de entorno y el servidor registra solo la superficie de lectura.
• Un solo host, una sola credencial. Habla con una única URL de Jenkins con un único token de API, configurado mediante variables de entorno. Sin superficie multi-tenant, sin bóveda de credenciales que pueda usarse mal.
• Con forma de triaje, no de API. Las herramientas responden a las preguntas que los agentes realmente hacen — "¿qué cambió entre el build A y el B?" (compare_builds), "¿qué pruebas en este job son flaky?" (get_flaky_candidates), "¿qué commits y archivos tocaron este build?" (get_scm_context) — en lugar de reflejar los endpoints de Jenkins uno a uno.
• Construido para ventanas de contexto. Cada herramienta de listado acepta un filtro RE2 y un límite. get_console_log_path devuelve la ruta en disco del registro de un build finalizado para que el agente pueda Read/Grep/Bash de forma nativa en lugar de transmitir gigabytes a través de MCP.
• Registros de consola con caché en disco. Los builds finalizados se guardan una vez y se reutilizan. La caché se clave por ruta de job + número de build, está limitada por tamaño total y se desaloja por mtime LRU.
• Consciente de Pipeline y Ginkgo. Más allá de la consola cruda, herramientas dedicadas analizan /wfapi/describe, /testReport/api/json y el bloque Summarizing N Failure de Ginkgo para que el agente obtenga información de fallos pre-digerida.
• Un único binario estático. Go puro. Sin runtime de Python, sin Docker requerido.

Herramientas

Las herramientas dirigidas a builds toman un job_path (separado por barras, p. ej. Builds/team/job-name) y un build_number opcional (0 u omitido = lastBuild). Una URL como https://jenkins.example.com/job/Builds/job/team/job/job-name/86/ se convierte en job_path="Builds/team/job-name", build_number=86. list_jobs toma un folder_path en la misma forma separada por barras (vacío = raíz).

Consulta docs/TOOLS.md para la referencia completa de parámetros.

Instalación

Binarios precompilados

Toma el archivo para tu sistema operativo y arquitectura desde la página de Releases y coloca el binario jenkins-mcp en tu PATH.

Vía go install

go install github.com/2001adarsh/jenkins-mcp-go@latest

El binario se coloca en $(go env GOBIN) (o $(go env GOPATH)/bin).

Vía Docker

Imágenes multi-arquitectura precompiladas se publican en GitHub Container Registry:

docker pull ghcr.io/2001adarsh/jenkins-mcp-go:latest

Etiquetas:

• :latest — la versión más reciente
• :vX.Y.Z — fijada a una versión específica
• :vX.Y.Z-amd64 / :vX.Y.Z-arm64 — por arquitectura (las etiquetas sin sufijo anteriores son manifiestos multi-arquitectura; docker pull resuelve la correcta automáticamente)

La imagen está construida sobre gcr.io/distroless/static:nonroot — se ejecuta como un usuario no root, incluye raíces de CA para que HTTPS a Jenkins funcione de inmediato, y pesa menos de 20 MB comprimida. Consulta la sección de configuración del cliente MCP Docker para una configuración de Claude Desktop basada en docker run.

Desde el código fuente

git clone https://github.com/2001adarsh/jenkins-mcp-go.git
cd jenkins-mcp-go
make build
./bin/jenkins-mcp -h 2>/dev/null || true   # the server speaks MCP over stdio; -h prints nothing

Configuración

La configuración se lee del entorno al inicio. No hay archivo de configuración ni banderas de línea de comandos — mantén las credenciales fuera de los argumentos del proceso.

Nota — JENKINS_API_TOKEN debe ser un token de API de Jenkins, no la contraseña de tu cuenta. En Jenkins, navega a tu menú de usuario → Configurar → Token de API → Agregar nuevo token.

Configuración del cliente MCP

El servidor habla MCP sobre stdio. Conéctalo agregando una entrada a la configuración del servidor MCP de tu cliente.

{
  "mcpServers": {
    "jenkins": {
      "command": "/usr/local/bin/jenkins-mcp",
      "env": {
        "JENKINS_URL": "https://jenkins.example.com",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "jenkins": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "JENKINS_URL",
        "-e", "JENKINS_USER",
        "-e", "JENKINS_API_TOKEN",
        "ghcr.io/2001adarsh/jenkins-mcp-go:latest"
      ],
      "env": {
        "JENKINS_URL": "https://jenkins.example.com",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-api-token"
      }
    }
  }
}

claude mcp add jenkins /usr/local/bin/jenkins-mcp \
  --env JENKINS_URL=https://jenkins.example.com \
  --env JENKINS_USER=your-username \
  --env JENKINS_API_TOKEN=your-api-token

{
  "command": "jenkins-mcp",
  "args": [],
  "env": {
    "JENKINS_URL": "https://jenkins.example.com",
    "JENKINS_USER": "your-username",
    "JENKINS_API_TOKEN": "your-api-token"
  }
}

Sesión de ejemplo

Una vez que el servidor esté registrado, pregúntale a tu agente cosas como:

• "¿Qué trabajos de pruebas de integración tenemos bajo Builds/team?" → llama a list_jobs con folder_path: "Builds/team", recursive: true, name_filter: "integration".
• "¿Cuál fue el resultado de la compilación 86 de Builds/team/integration-tests?" → llama a get_build_info.
• "Muéstrame las últimas 200 líneas de la ejecución más reciente de nightly." → llama a get_console_log con tail_lines: 200.
• "Encuentra cada línea que coincida con panic|fatal en la compilación 4521 con cinco líneas de contexto." → llama a search_console_log con pattern: "panic|fatal", context_lines: 5.
• "La compilación 91 pasó pero la 92 falló — ¿qué cambió?" → llama a compare_builds con build_a: 91, build_b: 92.
• "¿Qué pruebas en Builds/team/integration-tests han estado alternando entre pasar y fallar recientemente?" → llama a get_flaky_candidates.
• "¿Qué commits en la compilación 86 tocaron algo bajo internal/auth/?" → llama a get_scm_context con path_filter: "^internal/auth/".
• "¿Qué especificaciones de Ginkgo fallaron en la compilación 92 y cuál fue el primer error que emitió cada una?" → llama a get_ginkgo_failure_summary.
• "Almacena en caché el registro completo de la compilación 4521 para poder buscar en él localmente." → llama a get_console_log_path; el agente luego usa sus propias herramientas Read/Grep/Bash en la ruta devuelta.

Almacenamiento en caché

Solo las compilaciones finalizadas se almacenan en caché (el escritor requiere el marcador Finished: de Jenkins), y la caché se desaloja por LRU mtime una vez que supera JENKINS_MCP_CACHE_MAX. Los archivos viven en JENKINS_MCP_CACHE_DIR.

Notas de seguridad

• Sin eco de credenciales. El servidor nunca incluye credenciales en la salida de herramientas, mensajes de error o archivos en caché.
• Límite del sistema de archivos. Los nombres de archivo de la caché se sanean; el directorio de caché es la única ruta a la que el servidor escribe.

Si encuentras un problema de seguridad, sigue SECURITY.md en lugar de abrir un problema público.

Desarrollo

make build / test / lint / fmt. Consulta CONTRIBUTING.md para la guía completa de contribución y docs/DEBUGGING.md para saber cómo ejercitar el servidor localmente con MCP Inspector.

Compatibilidad

• Go: 1.23+
• Jenkins: cualquier versión que exponga los endpoints estándar /api/json, /consoleText, /wfapi/describe, /testReport/api/json. Las herramientas específicas de Pipeline requieren el complemento Pipeline.
• MCP: usa github.com/modelcontextprotocol/go-sdk v1.6+.

Alternativas

Cómo se compara jenkins-mcp-go con otras formas de exponer Jenkins a un LLM:

Si quieres una superficie pequeña y predecible adaptada a "el agente está depurando una compilación de Jenkins", este proyecto es para ti. Si necesitas un proxy JSON genérico o enrutamiento de credenciales multiinquilino, una puerta de enlace HTTP-MCP genérica es una mejor opción.

Preguntas frecuentes

¿Cómo conecto Jenkins a Claude?

Instala el binario jenkins-mcp, luego agrégalo a tu configuración MCP de Claude Desktop o Claude Code con tu JENKINS_URL, JENKINS_USER y JENKINS_API_TOKEN. Consulta Configuración del cliente MCP arriba para los fragmentos exactos de JSON / CLI.

¿Funciona esto con Cursor, Continue o Windsurf?

Sí. Cualquier cliente MCP que admita servidores stdio aceptará la misma configuración de command + env que se muestra en la sección Configuración del cliente MCP.

¿El servidor es de solo lectura?

Las lecturas siempre están activadas. Las herramientas de escritura (trigger_build, stop_build, cancel_queue_item) están registradas por defecto pero se pueden suprimir por completo estableciendo JENKINS_MCP_READONLY=1 — el servidor entonces nunca registra una herramienta mutadora, por lo que un agente literalmente no puede llamar a una.

¿Necesito un complemento de Jenkins para usar esto?

No se requiere ningún complemento adicional para las herramientas de lectura principales — acceden a endpoints estándar de Jenkins. Las herramientas específicas de Pipeline (get_pipeline_stages, get_stage_log) requieren el complemento Pipeline, que la mayoría de las instalaciones de Jenkins ya tienen.

¿Puede el agente LLM buscar en un registro de consola de varios gigabytes?

Sí. Usa get_console_log_path para forzar el almacenamiento en caché del registro completo de una compilación finalizada en disco; la herramienta devuelve una ruta local que el agente puede luego Read, Grep o Bash de forma nativa. La caché se desaloja por LRU y está limitada por JENKINS_MCP_CACHE_MAX.

¿Maneja específicamente fallos de pruebas de Ginkgo?

Sí. get_ginkgo_failure_summary analiza el bloque Summarizing N Failure de Ginkgo y superficie la primera línea [ERROR] etiquetada con el nombre de cada especificación más el contexto circundante — mucho más rápido que pedirle al agente que escanee todo el registro.

¿Es seguro darle a un LLM acceso al token de API de Jenkins?

El servidor usa el token de API de un solo usuario de Jenkins (no una contraseña), confinado a un JENKINS_URL. Combínalo con JENKINS_MCP_READONLY=1 y un usuario de Jenkins con privilegios mínimos para el valor predeterminado más seguro. Consulta SECURITY.md para el modelo de amenazas completo.

Licencia

MIT © Adarsh Singh