Jenkins MCP server

Por que jenkins-mcp-go?

A maioria das integrações com Jenkins espera um humano no teclado. Agentes de LLM precisam de algo diferente: respostas pequenas e estruturadas; um caminho claro de "build falhou" para "aqui está a linha que falhou"; e a capacidade de pesquisar um log de console de vários gigabytes sem baixá-lo novamente a cada pergunta.

jenkins-mcp-go foi construído para esse fluxo de trabalho:

• Leitura primeiro, gravações opt-out. As ferramentas de leitura estão sempre ativas. As ferramentas de gravação (trigger_build, stop_build, cancel_queue_item) são controladas por JENKINS_MCP_READONLY: defina a variável de ambiente e o servidor registra apenas a superfície de leitura.
• Host único, credencial única. Ele fala com uma única URL do Jenkins com um único token de API, configurado por variáveis de ambiente. Sem superfície multi-tenant, sem cofre de credenciais para uso indevido.
• Formato de triagem, não de API. As ferramentas respondem às perguntas que os agentes realmente fazem — "o que mudou entre a build A e a B?" (compare_builds), "quais testes neste job são instáveis?" (get_flaky_candidates), "quais commits e arquivos afetaram esta build?" (get_scm_context) — em vez de espelhar os endpoints do Jenkins um a um.
• Feito para janelas de contexto. Cada ferramenta de listagem aceita um filtro RE2 e um limite. get_console_log_path retorna o caminho em disco do log de uma build concluída para que o agente possa Read/Grep/Bash nativamente em vez de transmitir gigabytes pelo MCP.
• Logs de console em cache em disco. Builds concluídas são salvas uma vez e reutilizadas. O cache é indexado por caminho do job + número da build, limitado por tamanho total e removido por LRU mtime.
• Ciente de Pipeline e Ginkgo. Além do console bruto, ferramentas dedicadas analisam /wfapi/describe, /testReport/api/json e o bloco Summarizing N Failure do Ginkgo para que o agente receba informações de falha pré-digeridas.
• Um único binário estático. Go puro. Sem runtime Python, sem Docker necessário.

Ferramentas

As ferramentas direcionadas a builds aceitam um job_path (separado por barras, ex.: Builds/team/job-name) e um build_number opcional (0 ou omitido = lastBuild). Uma URL como https://jenkins.example.com/job/Builds/job/team/job/job-name/86/ vira job_path="Builds/team/job-name", build_number=86. list_jobs aceita um folder_path no mesmo formato separado por barras (vazio = raiz).

Consulte docs/TOOLS.md para a referência completa de parâmetros.

Instalação

Binários pré-compilados

Baixe o arquivo para seu sistema operacional e arquitetura na página de Releases e coloque o binário jenkins-mcp no seu PATH.

Via go install

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

O binário vai para $(go env GOBIN) (ou $(go env GOPATH)/bin).

Via Docker

Imagens multi-arquitetura pré-compiladas são publicadas no GitHub Container Registry:

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

Tags:

• :latest — release mais recente
• :vX.Y.Z — fixado em um release específico
• :vX.Y.Z-amd64 / :vX.Y.Z-arm64 — por arquitetura (as tags sem sufixo acima são manifests multi-arquitetura; docker pull resolve a correta automaticamente)

A imagem é construída sobre gcr.io/distroless/static:nonroot — executa como usuário não-root, inclui raízes de CA para que HTTPS para o Jenkins funcione de imediato e tem menos de 20 MB compactada. Consulte a seção Configuração do cliente MCP via Docker para uma configuração do Claude Desktop baseada em docker run.

A partir do código-fonte

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

Configuração

A configuração é lida do ambiente na inicialização. Não há arquivo de configuração nem flags de linha de comando — mantenha as credenciais fora dos argumentos do processo.

Nota — JENKINS_API_TOKEN deve ser um token de API do Jenkins, não a senha da sua conta. No Jenkins, navegue até o menu do usuário → Configure → API Token → Add new Token.

Configuração do cliente MCP

O servidor fala MCP via stdio. Conecte-o adicionando uma entrada à configuração do servidor MCP do seu 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"
  }
}

Sessão de exemplo

Depois que o servidor estiver registrado, pergunte ao seu agente coisas como:

• "Quais jobs de teste de integração temos em Builds/team?" → chama list_jobs com folder_path: "Builds/team", recursive: true, name_filter: "integration".
• "Qual foi o resultado do build 86 de Builds/team/integration-tests?" → chama get_build_info.
• "Mostre-me as últimas 200 linhas da execução mais recente de nightly." → chama get_console_log com tail_lines: 200.
• "Encontre todas as linhas que correspondem a panic|fatal no build 4521 com cinco linhas de contexto." → chama search_console_log com pattern: "panic|fatal", context_lines: 5.
• "O build 91 passou, mas o 92 falhou — o que mudou?" → chama compare_builds com build_a: 91, build_b: 92.
• "Quais testes em Builds/team/integration-tests têm alternado entre passou e falhou recentemente?" → chama get_flaky_candidates.
• "Quais commits no build 86 tocaram algo em internal/auth/?" → chama get_scm_context com path_filter: "^internal/auth/".
• "Quais specs Ginkgo falharam no build 92 e qual foi o primeiro erro que cada uma emitiu?" → chama get_ginkgo_failure_summary.
• "Armazene em cache o log completo do build 4521 para que eu possa fazer grep localmente." → chama get_console_log_path; o agente então usa suas próprias ferramentas Read/Grep/Bash no caminho retornado.

Cache

Somente builds concluídos são armazenados em cache (o escritor exige o marcador Finished: do Jenkins), e o cache é removido por LRU mtime quando excede JENKINS_MCP_CACHE_MAX. Os arquivos ficam em JENKINS_MCP_CACHE_DIR.

Notas de segurança

• Sem eco de credenciais. O servidor nunca inclui credenciais na saída das ferramentas, mensagens de erro ou arquivos em cache.
• Limite do sistema de arquivos. Os nomes dos arquivos de cache são saneados; o diretório de cache é o único caminho em que o servidor grava.

Se você encontrar um problema de segurança, siga SECURITY.md em vez de abrir uma issue pública.

Desenvolvimento

make build / test / lint / fmt. Consulte CONTRIBUTING.md para o guia completo do contribuidor e docs/DEBUGGING.md para saber como exercitar o servidor localmente com o MCP Inspector.

Compatibilidade

• Go: 1.23+
• Jenkins: qualquer versão que exponha os endpoints padrão /api/json, /consoleText, /wfapi/describe, /testReport/api/json. As ferramentas específicas de Pipeline exigem o plugin Pipeline.
• MCP: usa github.com/modelcontextprotocol/go-sdk v1.6+.

Alternativas

Como jenkins-mcp-go se compara a outras formas de expor o Jenkins a um LLM:

Se você quer uma superfície pequena e previsível voltada para "o agente está depurando um build do Jenkins", este projeto é para você. Se você precisa de um proxy JSON genérico ou roteamento de credenciais multi-tenant, um gateway HTTP-MCP genérico é mais adequado.

FAQ

Como conecto o Jenkins ao Claude?

Instale o binário jenkins-mcp e adicione-o à configuração MCP do seu Claude Desktop ou Claude Code com seu JENKINS_URL, JENKINS_USER e JENKINS_API_TOKEN. Consulte Configuração do cliente MCP acima para os exemplos exatos de JSON / CLI.

Isso funciona com Cursor, Continue ou Windsurf?

Sim. Qualquer cliente MCP que suporte servidores stdio aceitará a mesma configuração command + env mostrada na seção Configuração do cliente MCP.

O servidor é somente leitura?

As leituras estão sempre ativas. As ferramentas de escrita (trigger_build, stop_build, cancel_queue_item) são registradas por padrão, mas podem ser totalmente suprimidas definindo JENKINS_MCP_READONLY=1 — o servidor então nunca registra uma ferramenta de mutação, então um agente literalmente não pode chamar uma.

Preciso de um plugin Jenkins para usar isso?

Nenhum plugin extra é necessário para as ferramentas de leitura principais — elas acessam endpoints padrão do Jenkins. As ferramentas específicas de Pipeline (get_pipeline_stages, get_stage_log) exigem o plugin Pipeline, que a maioria das instalações do Jenkins já possui.

O agente LLM pode fazer grep em um log de console de vários gigabytes?

Sim. Use get_console_log_path para forçar o cache do log completo de um build concluído em disco; a ferramenta retorna um caminho local que o agente pode então Read, Grep, ou Bash nativamente. O cache é removido por LRU e limitado por JENKINS_MCP_CACHE_MAX.

Ele lida especificamente com falhas de teste Ginkgo?

Sim. get_ginkgo_failure_summary analisa o bloco Summarizing N Failure do Ginkgo e superfície a primeira linha [ERROR] marcada com o nome de cada spec, além do contexto ao redor — muito mais rápido do que pedir ao agente para escanear o log inteiro.

É seguro dar a um LLM acesso ao token da API do Jenkins?

O servidor usa o token da API de um único usuário do Jenkins (não uma senha), confinado a um JENKINS_URL. Combine com JENKINS_MCP_READONLY=1 e um usuário Jenkins de privilégios mínimos para o padrão mais seguro. Consulte SECURITY.md para o modelo de ameaça completo.

Licença

MIT © Adarsh Singh