Jenkins MCP Server

Um servidor MCP para automatizar tarefas e gerenciar jobs

Documentação

Jenkins MCP Server

Um servidor Model Context Protocol (MCP) que permite ao Claude interagir com o Jenkins por meio de várias ferramentas de automação. Este servidor fornece recursos abrangentes de gerenciamento do Jenkins, incluindo monitoramento de jobs, controle de builds e gerenciamento de fila.

Recursos

Gerenciamento de Jobs: Listar jobs, obter configurações de jobs e monitorar o status dos jobs
Controle de Builds: Disparar builds com parâmetros, parar builds em execução e verificar o status do build
Histórico de Builds: Recuperar histórico de builds e informações detalhadas do build
Logs do Console: Acessar a saída do console do build para depuração
Gerenciamento de Fila: Monitorar a fila de builds do Jenkins e builds travados
Suporte a Pastas: Navegar por pastas do Jenkins e estruturas organizacionais

Instalação

Clone o repositório:

git clone https://github.com/ddang-jung/jenkins-mcp-server.git
cd jenkins-mcp-server

Instale as dependências:

npm install

Compile o projeto:

npm run build

Configuração

Variáveis de Ambiente

Defina as seguintes variáveis de ambiente para autenticação no Jenkins:

JENKINS_URL: URL do seu servidor Jenkins (ex.: http://localhost:8080)
JENKINS_USER: Seu nome de usuário do Jenkins
JENKINS_TOKEN: Seu token de API do Jenkins (recomendado) ou senha

Obtendo o Token de API do Jenkins

Faça login no Jenkins
Vá para Gerenciar Jenkins → Gerenciar Usuários → Clique no seu nome de usuário
Clique em Configurar → Token de API → Adicionar novo Token
Copie o token gerado

Configuração do Git

O projeto inclui um arquivo .gitignore abrangente que exclui:

Artefatos de build (build/, dist/)
Dependências (node_modules/)
Variáveis de ambiente (.env*)
Credenciais do Jenkins e arquivos de configuração
Arquivos de IDE (.vscode/, .idea/)
Arquivos de sistema (.DS_Store, Thumbs.db)

Importante: Nunca envie credenciais do Jenkins ou tokens de API para o controle de versão.

Configuração do Claude Desktop

Adicione esta configuração ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "jenkins": {
      "command": "node",
      "args": ["/path/to/jenkins-mcp-server/build/index.js"],
      "env": {
        "JENKINS_URL": "http://your-jenkins-server:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_TOKEN": "your-api-token"
      }
    }
  }
}

Uso

Iniciando o Servidor

npm start

O servidor roda em stdio e se comunica com o Claude através do protocolo MCP.

Modo de Desenvolvimento

Para desenvolvimento com recompilação automática:

npm run watch

Para depuração com o MCP Inspector:

npm run inspector

Ferramentas Disponíveis

1. `get_build_status`

Obtenha o status de um build específico do Jenkins.

Parâmetros:

jobPath (obrigatório): Caminho para o job do Jenkins (ex.: "job/MyProject/job/main")
buildNumber (opcional): Número do build ou "lastBuild" para o mais recente

Exemplo:

{
  "jobPath": "job/MyProject",
  "buildNumber": "lastBuild"
}

2. `trigger_build`

Dispara um novo build do Jenkins com parâmetros opcionais.

Parâmetros:

jobPath (obrigatório): Caminho para o job do Jenkins
parameters (opcional): Parâmetros do build como pares chave-valor

Exemplo:

{
  "jobPath": "job/MyProject",
  "parameters": {
    "BRANCH": "main",
    "DEPLOY_ENV": "staging"
  }
}

3. `get_build_log`

Recupera a saída do console de um build específico.

Parâmetros:

jobPath (obrigatório): Caminho para o job do Jenkins
buildNumber (obrigatório): Número do build ou "lastBuild"

4. `list_jobs`

Lista todos os jobs do Jenkins em uma pasta ou no nível raiz.

Parâmetros:

folderPath (opcional): Caminho para a pasta (ex.: "job/MyFolder") ou vazio para a raiz

5. `get_build_history`

Obtém o histórico de builds de um job específico do Jenkins.

Parâmetros:

jobPath (obrigatório): Caminho para o job do Jenkins
limit (opcional): Número de builds recentes a recuperar (padrão: 10)

6. `stop_build`

Para um build em execução do Jenkins.

Parâmetros:

jobPath (obrigatório): Caminho para o job do Jenkins
buildNumber (obrigatório): Número do build ou "lastBuild"

7. `get_queue`

Obtém o status atual da fila de builds do Jenkins.

Parâmetros: Nenhum

8. `get_job_config`

Obtém os detalhes de configuração de um job do Jenkins.

Parâmetros:

jobPath (obrigatório): Caminho para o job do Jenkins

Formato do Caminho do Job

Os caminhos de jobs do Jenkins seguem este formato:

Job no nível raiz: job/JobName
Job em pasta: job/FolderName/job/JobName
Multi-nível: job/Folder1/job/Folder2/job/JobName

Tratamento de Erros

O servidor fornece tratamento abrangente de erros:

Erros de autenticação: Verifique suas credenciais do Jenkins
Job não encontrado: Verifique o formato do caminho do job
Erros de permissão: Garanta que seu usuário do Jenkins tenha as permissões adequadas
Erros de rede: Verifique a conectividade com o servidor Jenkins

Desenvolvimento

Estrutura do Projeto

jenkins-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md            # This file

Scripts

npm run build: Compilar TypeScript para JavaScript
npm run watch: Observar mudanças e recompilar
npm run inspector: Iniciar o MCP Inspector para depuração
npm run prepare: Preparar build (executa automaticamente)
npm run clean: Limpar artefatos de build e dependências (macOS/Linux)
npm run clean:win: Limpar artefatos de build e dependências (Windows)

Limpando o Projeto

Para redefinir o projeto ao seu estado inicial (remover artefatos de build e dependências):

macOS/Linux:

npm run clean
# or manually:
rm -rf node_modules build package-lock.json

Windows:

npm run clean:win
# or manually:
rmdir /s /q node_modules & rmdir /s /q build & del package-lock.json

Contribuindo

Faça um fork do repositório
Crie um branch de recurso
Faça suas alterações
Teste minuciosamente
Envie um pull request

Licença

Este projeto é licenciado sob a Licença MIT.

Solução de Problemas

Problemas Comuns

"Erro de API do Jenkins": Verifique sua URL e credenciais do Jenkins
"Job não encontrado": Verifique o formato do caminho do job (use o prefixo job/)
"Permissão negada": Garanta que seu usuário do Jenkins tenha as permissões necessárias
"Conexão recusada": Verifique se o servidor Jenkins está em execução e acessível

Modo de Depuração

Ative o registro de depuração definindo:

export DEBUG=jenkins-mcp-server

Para mais informações, visite a documentação da API REST do Jenkins.

Jenkins MCP Server

Documentação