Log-MCP

Log-MCP é um serviço remoto de consulta de logs baseado no Model Context Protocol (MCP), que se conecta a servidores remotos via SSH para fornecer capacidade de consulta de logs para assistentes de IA como o Claude Code. O projeto suporta dois modos de transporte, HTTP e STDIO, podendo ser facilmente integrado a diversos ambientes de desenvolvimento.

GitHub
4
Experimente este MCPPatrocinado

Documentação

Log-MCP

GitHub Stars GitHub forks AUR

Introdução

Log-MCP é um serviço de consulta de logs remotos baseado no Model Context Protocol (MCP), que se conecta a servidores remotos via SSH, fornecendo capacidade de consulta de logs para assistentes de IA como o Claude Code. O projeto suporta dois modos de transporte: HTTP e STDIO, podendo ser facilmente integrado a diversos ambientes de desenvolvimento.

Principais Recursos

  • Suporte a múltiplos servidores - Suporta a configuração de vários servidores remotos, gerenciando consultas de logs de forma unificada
  • Pool de conexões SSH - Gerenciamento eficiente de pool de conexões SSH, com suporte a reutilização de conexões e reconexão automática
  • Múltiplas operações de log - Suporta listar arquivos de log, ler conteúdo de logs, pesquisar logs e visualizar o final dos logs em tempo real
  • Modos de transporte flexíveis - Suporta dois modos de transporte: HTTP e STDIO, adaptando-se a diferentes cenários de uso
  • Garantia de segurança - Múltiplos mecanismos de segurança, como validação de parâmetros, validação de caminhos e escape de Shell
  • Filtro por nível de log - Suporta filtragem de consultas por nível de log (info, warn, error, debug)
  • Pesquisa com expressões regulares - Suporta pesquisa de conteúdo de logs usando expressões regulares
  • Exibição de linhas de contexto - Os resultados da pesquisa podem exibir o conteúdo de contexto das linhas correspondentes

Princípios de Implementação e Tecnologias-Chave

  • Protocolo MCP - Implementa a especificação do Model Context Protocol, fornecendo uma interface padronizada de chamada de ferramentas
  • Apache MINA SSHD - Implementa conexão SSH e execução de comandos com base no Apache MINA SSHD
  • Tecnologia de pool de conexões - Usa Apache Commons Pool2 para gerenciamento do pool de conexões SSH
  • Modo de transporte duplo - Suporta Undertow HTTP Server e STDIO como métodos de transporte
  • JSON-RPC 2.0 - Processamento de requisições e respostas baseado no protocolo JSON-RPC 2.0

Ambiente de Execução

  • JDK 21+
  • Maven 3.6+
  • Arquivo de chave privada SSH (para conectar ao servidor remoto)

Início Rápido

1. Construir o Projeto

cd log-mcp
mvn clean package

Após a construção, o arquivo log-mcp-1.0.0.jar será gerado no diretório target.

2. Configurar Informações do Servidor

Edite o arquivo src/main/resources/config.json para configurar as informações do servidor remoto:

{
  "servers": [
    {
      "name": "local-server",
      "host": "192.168.5.169",
      "port": 22,
      "username": "root",
      "privateKeyPath": "${ssh.cert.path}",
      "logRootPath": "/home/docker/logs/fantomfite-admin/",
      "description": "169测试服务器",
      "default": true
    }
  ],
  "logLevels": ["info", "warn", "error", "debug"],
  "logFilePattern": "{level}/log-{level}-{date}.{seq}.log"
}

3. Configurar Autenticação SSH

O Log-MCP atualmente suporta autenticação via arquivo de chave privada SSH para conectar a servidores remotos.

Autenticação com Chave Privada SSH

  1. Gere um par de chaves SSH (se ainda não tiver):
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
  1. Adicione a chave pública ao servidor remoto:
ssh-copy-id -i ~/.ssh/id_rsa.pub root@192.168.5.169

Ou adicione manualmente o conteúdo da chave pública ao arquivo ~/.ssh/authorized_keys no servidor remoto.

  1. Garanta que as permissões do arquivo de chave privada estejam corretas:
chmod 600 ~/.ssh/id_rsa
  1. Verifique a conexão SSH:
ssh -i ~/.ssh/id_rsa root@192.168.5.169

Observações:

  • O caminho do arquivo de chave privada é especificado no arquivo de configuração pelo campo privateKeyPath
  • Suporta o uso de variáveis de ambiente, como ${ssh.cert.path}
  • Garanta que o formato do arquivo de chave privada esteja correto (suporta formatos OpenSSH e PEM)
  • Atualmente não suporta autenticação por senha, apenas autenticação por arquivo de chave privada

4. Adicionar o Serviço MCP

Método 1: Modo STDIO (Recomendado)

claude mcp add log-mcp-stdio java -- \
  -Dssh.cert.path=/Users/jianyingcai/id_rsa \
  -Dlog.config=/Users/jianyingcai/IdeaProjects/mcp/log-mcp/target/classes/config.json \
  -jar /Users/jianyingcai/IdeaProjects/mcp/log-mcp/target/log-mcp-1.0.0.jar

Método 2: Modo HTTP

Primeiro, inicie o serviço HTTP:

java -Dtransport.mode=http \
     -Dserver.port=8892 \
     -Dssh.cert.path=/Users/jianyingcai/id_rsa \
     -Dlog.config=/Users/jianyingcai/IdeaProjects/mcp/log-mcp/target/classes/config.json \
     -jar target/log-mcp-1.0.0.jar

Depois, adicione o serviço MCP:

claude mcp add --transport http log-mcp http://127.0.0.1:8892/mcp

5. Verificar a Instalação

cat ~/.claude.json | grep 'log-mcp' -C 5

Ferramentas Disponíveis

O Log-MCP fornece as seguintes ferramentas para uso pelos assistentes de IA:

list_servers

Lista as informações de todos os servidores configurados.

Exemplo de retorno:

{
  "servers": [
    {
      "name": "local-server",
      "host": "192.168.5.169",
      "description": "169测试服务器",
      "status": "connected"
    }
  ]
}

list_log_files

Lista os arquivos de log no servidor especificado.

Parâmetros:

  • server (opcional): Nome do servidor de destino
  • level (opcional): Filtro por nível de log
  • startDate (opcional): Data de início (YYYY-MM-DD)
  • endDate (opcional): Data de término (YYYY-MM-DD)

Exemplo de retorno:

{
  "server": "local-server",
  "files": [
    {
      "path": "error/log-error-2026-05-04.0.log",
      "size": "4.3KB",
      "level": "error",
      "lastModified": "2026-05-04 04:22:28"
    }
  ],
  "totalFiles": 1
}

read_log_file

Lê o conteúdo de um arquivo de log especificado.

Parâmetros:

  • filePath (obrigatório): Caminho relativo do arquivo de log
  • server (opcional): Nome do servidor de destino
  • startLine (opcional): Número da linha inicial
  • endLine (opcional): Número da linha final
  • maxLines (opcional): Número máximo de linhas a ler

Exemplo de retorno:

{
  "server": "local-server",
  "file": "error/log-error-2026-05-04.0.log",
  "totalLines": 45,
  "lines": ["2026-05-04 04:22:28.774 [http-nio-8888-exec-9] ERROR ..."]
}

search_logs

Pesquisa palavras-chave em arquivos de log.

Parâmetros:

  • keyword (obrigatório): Palavra-chave de pesquisa
  • server (opcional): Nome do servidor de destino
  • levels (opcional): Array de níveis de log, padrão ["debug", "info"]
  • startDate (opcional): Data de início (YYYY-MM-DD)
  • endDate (opcional): Data de término (YYYY-MM-DD)
  • useRegex (opcional): Se deve usar expressões regulares
  • contextLines (opcional): Número de linhas de contexto
  • maxResults (opcional): Número máximo de resultados

Exemplo de retorno:

{
  "server": "local-server",
  "keyword": "ERROR",
  "results": [
    {
      "file": "error/log-error-2026-05-04.0.log",
      "lineNumber": 1,
      "content": "2026-05-04 04:22:28.774 [http-nio-8888-exec-9] ERROR ..."
    }
  ],
  "totalMatches": 1
}

tail_logs

Obtém as linhas de log mais recentes.

Parâmetros:

  • server (opcional): Nome do servidor de destino
  • level (opcional): Nível de log, padrão "info"
  • lines (opcional): Número de linhas, padrão 50

Exemplo de retorno:

{
  "server": "local-server",
  "file": "info/log-info-2026-05-06.0.log",
  "totalLines": 50,
  "lines": ["2026-05-06 10:30:15.123 [main] INFO ..."]
}

Configuração

Configuração do Servidor

{
  "name": "server-name",           // 服务器名称（唯一标识）
  "host": "192.168.1.100",         // 服务器地址
  "port": 22,                      // SSH 端口
  "username": "root",              // SSH 用户名
  "privateKeyPath": "${ssh.cert.path}",  // SSH 私钥路径（支持环境变量）
  "logRootPath": "/var/logs/",     // 日志根目录
  "description": "生产服务器",      // 服务器描述
  "default": true                  // 是否为默认服务器
}

Configuração do Pool de Conexões SSH

{
  "sshPool": {
    "maxConnectionsPerServer": 3,  // 每个服务器最大连接数
    "connectionTimeout": 30000,    // 连接超时时间（毫秒）
    "idleTimeout": 300000,         // 空闲超时时间（毫秒）
    "maxRetries": 2                // 最大重试次数
  }
}

Configuração Padrão de Consulta

{
  "queryDefaults": {
    "maxResults": 100,             // 默认最大结果数
    "maxResultsLimit": 1000,       // 最大结果数限制
    "maxReadLines": 500,           // 默认最大读取行数
    "maxReadLinesLimit": 5000,     // 最大读取行数限制
    "contextLines": 3,             // 默认上下文行数
    "searchTimeout": 30000,        // 搜索超时时间（毫秒）
    "defaultTailLines": 50         // 默认 tail 行数
  }
}

Exemplos de Uso

No Claude Code, você pode consultar logs diretamente usando linguagem natural:

帮我查看 5.9 服务器上最近的错误日志

搜索包含 "NullPointerException" 的日志

查看 local-server 上 2026-05-04 的所有日志文件

读取最新的 100 行 info 日志

Recursos de Segurança

  • Validação de parâmetros - Todos os parâmetros de entrada passam por validação rigorosa
  • Validação de caminhos - Previne ataques de travessia de diretórios
  • Escape de Shell - Todos os parâmetros de comandos Shell passam por tratamento de escape
  • Autenticação por chave privada SSH - Suporta apenas autenticação por arquivo de chave privada SSH, não suporta autenticação por senha, fornecendo maior segurança
  • Gerenciamento do pool de conexões - Gerencia automaticamente o ciclo de vida das conexões, prevenindo vazamento de recursos

Solução de Problemas

Falha na Conexão SSH

  1. Verifique as permissões da chave privada SSH:
chmod 600 ~/id_rsa
  1. Verifique a conexão SSH:
ssh -i ~/id_rsa root@192.168.5.169
  1. Verifique se o caminho no arquivo de configuração está correto

Arquivo de Log Não Encontrado

  1. Confirme se a configuração de logRootPath está correta
  2. Verifique se o formato de nomenclatura do arquivo de log corresponde a logFilePattern
  3. Verifique se o arquivo de log existe no servidor

Serviço MCP Sem Resposta

  1. Verifique se o serviço foi iniciado corretamente
  2. Verifique a saída de logs para mensagens de erro
  3. Verifique se a configuração de ~/.claude.json está correta

Stack Tecnológico

  • Java 21 - Linguagem de programação
  • Maven - Ferramenta de construção do projeto
  • Apache MINA SSHD 2.12.0 - Cliente SSH
  • Jackson 2.17.0 - Serialização/desserialização JSON
  • Apache Commons Pool2 2.12.0 - Gerenciamento de pool de conexões
  • Undertow 2.3.12 - Servidor HTTP (modo HTTP)
  • SLF4J + Logback - Framework de logs

Estrutura do Projeto

log-mcp/
├── src/main/java/com/example/logmcp/
│   ├── LogMcpServer.java           # 主入口
│   ├── config/                     # 配置管理
│   ├── model/                      # 数据模型
│   ├── pool/                       # SSH 连接池
│   ├── protocol/                   # JSON-RPC 协议
│   ├── security/                   # 安全验证
│   ├── service/                    # 业务逻辑
│   ├── tools/                      # MCP 工具实现
│   └── transport/                  # 传输层（HTTP/STDIO）
├── src/main/resources/
│   ├── config.json                 # 服务器配置
│   └── logback.xml                 # 日志配置
└── pom.xml                         # Maven 配置

Guia de Contribuição

Sinta-se à vontade para enviar Issues e Pull Requests!

  1. Faça um fork deste repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/AmazingFeature)
  3. Envie suas alterações (git commit -m 'Add some AmazingFeature')
  4. Envie para o branch (git push origin feature/AmazingFeature)
  5. Envie um Pull Request

Licença

Este projeto é licenciado sob a Licença Apache 2.0 - consulte o arquivo LICENSE para mais detalhes

Considerações Finais

Se este projeto foi útil para você, sinta-se à vontade para dar uma estrela (Star). Se tiver sugestões, por favor, abra uma Issue. Vamos evoluir juntos!

Contato