@grec0/mcp-jenkins

MCP server para operar Jenkins desde clientes compatibles con Model Context Protocol, como VS Code, Claude Desktop u otros agentes. Permite consultar jobs, lanzar builds, esperar a que terminen, revisar logs, inspeccionar stages de pipelines, gestionar approvals, consultar artifacts/cobertura y administrar jobs sin entrar en la UI de Jenkins.

Que Puedes Hacer

Listar jobs, multibranch projects y ramas.
Consultar estado, configuracion y ultimo build de un job.
Lanzar builds con o sin parametros.
Esperar de forma bloqueante hasta que un build termine.
Ver historial de builds, logs, stages, nodos y acciones pendientes.
Detener builds con confirmacion explicita.
Hacer rebuild/replay si Jenkins tiene los endpoints/plugins necesarios.
Crear, actualizar, habilitar, deshabilitar o borrar jobs usando confirmaciones de seguridad.
Consultar reportes de cobertura cuando el job los publique.

Quick Start

Requisitos

Node.js 18 o superior.
URL de Jenkins accesible desde la maquina donde corre el cliente MCP.
Usuario de Jenkins con permisos suficientes.
API token o password de Jenkins.

Usa API tokens cuando sea posible. No guardes credenciales reales en repositorios ni compartas configuraciones con secretos.

Configuracion Recomendada Con npx

{
  "servers": {
    "jenkins": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--package", "@grec0/mcp-jenkins@latest", "mcp-jenkins"],
      "env": {
        "JENKINS_URL": "https://tu-jenkins.com/jenkins",
        "JENKINS_USERNAME": "tu-usuario",
        "JENKINS_PASSWORD": "tu-api-token"
      }
    }
  }
}

Para fijar una version concreta, cambia @latest por una version publicada:

"args": ["-y", "--package", "@grec0/[email protected]", "mcp-jenkins"]

Instalacion Global Opcional

npm install -g @grec0/mcp-jenkins

Configuracion usando el binario global:

{
  "servers": {
    "jenkins": {
      "type": "stdio",
      "command": "mcp-jenkins",
      "env": {
        "JENKINS_URL": "https://tu-jenkins.com/jenkins",
        "JENKINS_USERNAME": "tu-usuario",
        "JENKINS_PASSWORD": "tu-api-token"
      }
    }
  }
}

Conceptos Basicos

`fullName`

La mayoria de herramientas nuevas usan fullName, que es la ruta logica del job en Jenkins.

Ejemplos:

Grec0AI_backend_sb
Grec0AI_backend_sb/main
folder/backend/main

En un multibranch project, normalmente el primer nivel es el proyecto y el segundo nivel es la rama. Por ejemplo, si Jenkins muestra:

Grec0AI_backend_sb / main

el fullName suele ser:

Grec0AI_backend_sb/main

`app` y `branch`

Las tools antiguas usan app y branch. Siguen disponibles por compatibilidad, pero para uso nuevo se recomienda usar los managers basados en fullName.

Managers vs Tools Simples

Usa jenkins_job_manager para jobs y pipelines.
Usa jenkins_build_manager para ejecuciones/builds.
Usa jenkins_wait_for_build cuando un agente deba esperar a Jenkins antes de continuar.
Usa jenkins_pipeline_monitor para stages, nodos e inputs pendientes.
Usa las tools jenkins_get_*, jenkins_start_job y jenkins_stop_job si ya tienes prompts antiguos basados en app y branch.

Flujos Recomendados

Descubrir Jobs

{
  "action": "list",
  "limit": 20
}

Tool: jenkins_job_manager

Listar Ramas De Un Multibranch Project

{
  "action": "list",
  "folder": "Grec0AI_backend_sb",
  "limit": 20
}

Tool: jenkins_job_manager

Lanzar Un Build Y Esperar A Que Termine

Inicia el build.

{
  "action": "start",
  "fullName": "Grec0AI_backend_sb/main"
}

Tool: jenkins_build_manager

Lista builds para identificar el numero iniciado.

{
  "action": "list",
  "fullName": "Grec0AI_backend_sb/main",
  "limit": 5
}

Tool: jenkins_build_manager

Espera hasta que Jenkins termine.

{
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "pollIntervalSeconds": 10,
  "timeoutSeconds": 1800,
  "includeStages": true
}

Tool: jenkins_wait_for_build

Solo despues de recibir completed: true, revisa logs, stages o ejecuta validaciones dependientes del build.

Revisar Un Fallo

{
  "action": "console",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "limit": 8000
}

Tool: jenkins_build_manager

{
  "action": "steps",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298
}

Tool: jenkins_pipeline_monitor

Aprobar O Rechazar Un Input Pendiente

Consulta inputs pendientes.

{
  "action": "pending_inputs",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298
}

Tool: jenkins_pipeline_monitor

Envia la decision usando la proceedUrl o abortUrl devuelta por Jenkins.

{
  "action": "submit_input",
  "decisionUrl": "https://tu-jenkins.com/jenkins/job/.../proceedEmpty"
}

Tool: jenkins_pipeline_monitor

Tools

`jenkins_job_manager`

Gestiona jobs y pipelines usando rutas fullName.

Acciones:

Accion	Descripcion
`list`	Lista jobs del root o de un folder/multibranch project.
`get`	Obtiene detalle de un job.
`get_config`	Devuelve el `config.xml` de un job.
`create_pipeline`	Crea un job/pipeline desde XML.
`update_config`	Actualiza `config.xml`; requiere `confirmName`.
`delete`	Borra un job; requiere `confirmName`.
`enable`	Habilita un job; requiere `confirmName`.
`disable`	Deshabilita un job; requiere `confirmName`.
`get_branches`	Lista ramas usando el flujo legacy basado en `app`.

Parametros:

Parametro	Uso
`action`	Accion a ejecutar.
`fullName`	Ruta del job, por ejemplo `folder/job/main`.
`folder`	Folder o multibranch project desde el que listar.
`query`	Filtro por texto para `list`.
`limit`	Maximo de resultados para `list`.
`configXml`	XML completo para crear o actualizar jobs.
`confirmName`	Confirmacion exacta para acciones protegidas.
`app`	Nombre de aplicacion para `get_branches`.

Ejemplos:

{
  "action": "list",
  "query": "backend",
  "limit": 20
}

{
  "action": "get",
  "fullName": "Grec0AI_backend_sb/main"
}

{
  "action": "get_config",
  "fullName": "Grec0AI_backend_sb/main"
}

{
  "action": "update_config",
  "fullName": "sandbox/test-pipeline",
  "configXml": "<flow-definition>...</flow-definition>",
  "confirmName": "sandbox/test-pipeline"
}

{
  "action": "delete",
  "fullName": "sandbox/test-pipeline",
  "confirmName": "sandbox/test-pipeline"
}

`jenkins_build_manager`

Gestiona ejecuciones de Jenkins.

Acciones:

Accion	Descripcion
`list`	Lista builds recientes de un job.
`get`	Obtiene detalle de un build.
`start`	Inicia un build, opcionalmente con parametros.
`wait`	Espera hasta que un build termine o alcance timeout.
`stop`	Detiene un build; requiere `confirmBuild`.
`rebuild`	Solicita reconstruccion si Jenkins expone el endpoint.
`replay`	Solicita replay si Jenkins expone el endpoint.
`console`	Devuelve logs de consola.
`artifacts`	Lista artifacts archivados con URLs.

Parametros:

Parametro	Uso
`action`	Accion a ejecutar.
`fullName`	Ruta del job.
`buildNumber`	Numero de build para acciones sobre una ejecucion.
`parameters`	Parametros para `buildWithParameters`.
`pollIntervalSeconds`	Intervalo entre consultas para `wait`.
`timeoutSeconds`	Tiempo maximo de espera para `wait`.
`includeStages`	Incluye stages al terminar el build.
`limit`	Cantidad de builds o caracteres de log.
`start`	Offset para logs progresivos.
`confirmBuild`	Confirmacion exacta para `stop`.

Ejemplos:

{
  "action": "list",
  "fullName": "Grec0AI_backend_sb/main",
  "limit": 10
}

{
  "action": "start",
  "fullName": "Grec0AI_backend_sb/main",
  "parameters": {
    "DEPLOY_ENV": "dev"
  }
}

{
  "action": "wait",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "pollIntervalSeconds": 10,
  "timeoutSeconds": 1800,
  "includeStages": true
}

{
  "action": "console",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "limit": 12000
}

{
  "action": "stop",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "confirmBuild": 298
}

`jenkins_wait_for_build`

Tool dedicada para agentes que necesitan bloquear el flujo hasta que Jenkins termine un build. La llamada responde cuando el build finaliza, cuando se alcanza el timeout o cuando Jenkins entra en una pausa manual (input) que requiere aprobación.

Parametros:

Parametro	Default	Descripcion
`fullName`	Requerido	Ruta del job.
`buildNumber`	Requerido	Numero de build a esperar.
`pollIntervalSeconds`	`10`	Segundos entre consultas. Minimo efectivo: 2. Maximo efectivo: 120.
`timeoutSeconds`	`1800`	Timeout total. Maximo efectivo: 86400.
`includeStages`	`true`	Incluye stages al terminar si el job expone Pipeline REST API.

Ejemplo:

{
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "pollIntervalSeconds": 10,
  "timeoutSeconds": 1800,
  "includeStages": true
}

Respuesta esperada:

{
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "completed": true,
  "timedOut": false,
  "waitedSeconds": 120,
  "pollCount": 13,
  "result": "SUCCESS",
  "build": { "number": 298 },
  "stages": []
}

Si Jenkins queda pausado esperando aprobación manual, la tool devuelve waitingForInput: true, el objeto pendingInput con proceedUrl/abortUrl y un nextStep con la llamada exacta a jenkins_submit_input_action.

Si timedOut es true, el build seguía corriendo cuando se alcanzó el timeout.

`jenkins_pipeline_monitor`

Inspecciona detalles especificos de pipelines.

Acciones:

Accion	Descripcion
`steps`	Devuelve stages del build.
`node`	Devuelve detalle de un nodo/stage por `nodeId`.
`pending_inputs`	Devuelve input actions pendientes.
`submit_input`	Envia una decision usando `decisionUrl`.

Ejemplos:

{
  "action": "steps",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 296
}

{
  "action": "node",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 296,
  "nodeId": "20"
}

{
  "action": "pending_inputs",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298
}

{
  "action": "submit_input",
  "decisionUrl": "https://tu-jenkins.com/jenkins/job/.../proceedEmpty"
}

Tools Simples Y Compatibilidad

Estas tools siguen disponibles para prompts antiguos o flujos simples basados en app y branch.

Tool	Uso
`jenkins_get_job_status`	Estado de un job por `app` y `branch`.
`jenkins_start_job`	Inicia un job con una rama.
`jenkins_stop_job`	Detiene un build por `app`, `branch` y `buildNumber`.
`jenkins_get_build_steps`	Stages de un build.
`jenkins_get_node_status`	Estado de un nodo de pipeline.
`jenkins_get_pending_actions`	Input actions pendientes.
`jenkins_submit_input_action`	Envia approval/reject usando una URL de Jenkins.
`jenkins_get_coverage_report`	Resumen de cobertura.
`jenkins_get_coverage_lines`	Cobertura de un archivo.
`jenkins_get_coverage_paths`	Paths con cobertura disponible.
`jenkins_get_git_branches`	Ramas Git disponibles para un job legacy.

Ejemplo legacy:

{
  "app": "mi-app",
  "branch": "main"
}

Operaciones Protegidas

Algunas acciones pueden cambiar o destruir configuracion en Jenkins. El MCP exige confirmacion explicita.

Accion	Confirmacion
`jenkins_job_manager.update_config`	`confirmName` debe ser igual a `fullName`.
`jenkins_job_manager.delete`	`confirmName` debe ser igual a `fullName`.
`jenkins_job_manager.enable`	`confirmName` debe ser igual a `fullName`.
`jenkins_job_manager.disable`	`confirmName` debe ser igual a `fullName`.
`jenkins_build_manager.stop`	`confirmBuild` debe ser igual a `buildNumber`.

Recomendacion: prueba primero create_pipeline, update_config y delete en un job temporal.

Requisitos De Jenkins

Funcionalidad disponible con Jenkins core:

Listar jobs.
Consultar job/build.
Iniciar builds.
Detener builds.
Leer logs.
Leer y actualizar config.xml si el usuario tiene permisos.
Listar artifacts archivados.

Plugins recomendados para funcionalidad completa:

Plugin	Para Que Sirve
`pipeline-rest-api`	Stages, nodos e input actions de pipelines.
`git-parameter`	Listado de ramas en tools legacy.
`jacoco`	Cobertura backend Java.
Cobertura frontend/Istanbul	Cobertura frontend si el job publica el ZIP esperado.

Consulta JENKINS_REQUIREMENTS.md para detalle de plugins, endpoints y errores comunes.

Respuestas Y Limites

Las tools devuelven JSON serializado como contenido de texto MCP.
console puede limitar logs con limit para evitar respuestas enormes.
artifacts devuelve metadata y URLs; no descarga binarios por defecto.
coverage depende mucho de como el job publique sus reportes.
jenkins_wait_for_build mantiene la llamada abierta hasta fin de build, timeout o pausa manual con input pendiente; ajusta timeoutSeconds para builds largos.

Troubleshooting

`ERR_MODULE_NOT_FOUND` con `zod-to-json-schema`

Si ves un error parecido a:

Cannot find module '.../zod-to-json-schema/dist/esm/parsers/record.js'

usa una version reciente del paquete y preferiblemente arranca con --package:

"args": ["-y", "--package", "@grec0/mcp-jenkins@latest", "mcp-jenkins"]

Si npx quedo con una instalacion temporal contaminada, borra la carpeta _npx que aparece en el stacktrace o limpia el cache de npm.

`401` O `403`

Revisa JENKINS_USERNAME, JENKINS_PASSWORD, API token y permisos del usuario en Jenkins.

`404` En `/wfapi/describe`

El job puede no ser Pipeline o puede faltar el plugin pipeline-rest-api.

No Encuentro El `fullName`

Primero lista jobs desde el root:

{
  "action": "list",
  "limit": 50
}

Despues lista dentro del multibranch project:

{
  "action": "list",
  "folder": "nombre-del-proyecto",
  "limit": 50
}

`jenkins_wait_for_build` Agota Timeout

El build seguía corriendo. Sube timeoutSeconds, revisa logs con console o consulta el build con jenkins_build_manager get. Si la respuesta incluye waitingForInput: true, aprueba o aborta con jenkins_submit_input_action usando la decisionUrl devuelta.

Desarrollo Local

Esta seccion es solo para quienes quieran modificar el paquete.

npm install
npm run build
npm test
npm run prerelease

No publiques una version nueva sin ejecutar npm run prerelease.

Licencia

MIT

Jenkins

@grec0/mcp-jenkins

Que Puedes Hacer

Quick Start

Requisitos

Configuracion Recomendada Con npx

Instalacion Global Opcional

Conceptos Basicos

fullName

app y branch

Managers vs Tools Simples

Flujos Recomendados

Descubrir Jobs

Listar Ramas De Un Multibranch Project

Lanzar Un Build Y Esperar A Que Termine

Revisar Un Fallo

Aprobar O Rechazar Un Input Pendiente

Tools

jenkins_job_manager

jenkins_build_manager

jenkins_wait_for_build

jenkins_pipeline_monitor

Tools Simples Y Compatibilidad

Operaciones Protegidas

Requisitos De Jenkins

Respuestas Y Limites

Troubleshooting

ERR_MODULE_NOT_FOUND con zod-to-json-schema

401 O 403

404 En /wfapi/describe

No Encuentro El fullName

jenkins_wait_for_build Agota Timeout

Desarrollo Local

Licencia

Servidores relacionados

Alpha Vantage MCP Server

Node.js Sandbox MCP Server

Lingo.dev

Seiro MCP

Sleep MCP Server

Unstructured

MCP Spine

Squads MCP

Zip1

Bitcoin MCP

UntitledUI MCP

`fullName`

`app` y `branch`

`jenkins_job_manager`

`jenkins_build_manager`

`jenkins_wait_for_build`

`jenkins_pipeline_monitor`

`ERR_MODULE_NOT_FOUND` con `zod-to-json-schema`

`401` O `403`

`404` En `/wfapi/describe`

No Encuentro El `fullName`

`jenkins_wait_for_build` Agota Timeout