Log-MCP

Log-MCP 是一个基于 Model Context Protocol (MCP) 的远程日志查询服务，通过 SSH 连接远程服务器，为 Claude Code 等 AI 助手提供日志查询能力。该项目支持 HTTP 和 STDIO 两种传输模式，可以方便地集成到各种开发环境中。

GitHub

Prueba este MCPPatrocinado

Documentación

Log-MCP

Introducción

Log-MCP es un servicio de consulta de registros remotos basado en el Model Context Protocol (MCP), que se conecta a servidores remotos mediante SSH para proporcionar capacidades de consulta de registros a asistentes de IA como Claude Code. El proyecto admite dos modos de transporte: HTTP y STDIO, y puede integrarse fácilmente en diversos entornos de desarrollo.

Características principales

Soporte multi-servidor - Admite la configuración de múltiples servidores remotos para gestionar consultas de registros de forma unificada
Pool de conexiones SSH - Gestión eficiente del pool de conexiones SSH, con soporte para reutilización de conexiones y reconexión automática
Múltiples operaciones de registro - Admite listar archivos de registro, leer contenido de registros, buscar registros y ver el final de los registros en tiempo real
Modos de transporte flexibles - Admite dos modos de transporte: HTTP y STDIO, adaptándose a diferentes escenarios de uso
Garantía de seguridad - Múltiples mecanismos de seguridad como validación de parámetros, validación de rutas y escape de Shell
Filtrado por nivel de registro - Admite filtrado de consultas por nivel de registro (info, warn, error, debug)
Búsqueda con expresiones regulares - Admite búsqueda de contenido de registros mediante expresiones regulares
Visualización de líneas de contexto - Los resultados de búsqueda pueden mostrar el contexto de las líneas coincidentes

Principios de implementación y tecnologías clave

Protocolo MCP - Implementa la especificación del Model Context Protocol, proporcionando una interfaz estandarizada de invocación de herramientas
Apache MINA SSHD - Implementa conexiones SSH y ejecución de comandos basado en Apache MINA SSHD
Tecnología de pool de conexiones - Utiliza Apache Commons Pool2 para la gestión del pool de conexiones SSH
Doble modo de transporte - Admite dos métodos de transporte: Undertow HTTP Server y STDIO
JSON-RPC 2.0 - Procesamiento de solicitudes y respuestas basado en el protocolo JSON-RPC 2.0

Entorno de ejecución

JDK 21+
Maven 3.6+
Archivo de clave privada SSH (para conectarse a servidores remotos)

Inicio rápido

1. Construir el proyecto

cd log-mcp
mvn clean package

Una vez completada la construcción, se generará el archivo log-mcp-1.0.0.jar en el directorio target.

2. Configurar la información del servidor

Edite el archivo src/main/resources/config.json para configurar la información del 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 la autenticación SSH

Log-MCP actualmente admite la conexión a servidores remotos mediante autenticación con archivo de clave privada SSH.

Autenticación con clave privada SSH

Genere un par de claves SSH (si aún no tiene uno):

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Agregue la clave pública al servidor remoto:

ssh-copy-id -i ~/.ssh/id_rsa.pub root@192.168.5.169

O agregue manualmente el contenido de la clave pública al archivo ~/.ssh/authorized_keys del servidor remoto.

Asegúrese de que los permisos del archivo de clave privada sean correctos:

chmod 600 ~/.ssh/id_rsa

Verifique la conexión SSH:

ssh -i ~/.ssh/id_rsa root@192.168.5.169

Notas:

La ruta del archivo de clave privada se especifica mediante el campo privateKeyPath en el archivo de configuración
Admite el uso de variables de entorno, como ${ssh.cert.path}
Asegúrese de que el formato del archivo de clave privada sea correcto (admite formatos OpenSSH y PEM)
Actualmente no se admite la autenticación por contraseña, solo la autenticación con archivo de clave privada

4. Agregar el servicio MCP

Opción 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

Opción 2: Modo HTTP

Primero inicie el servicio 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

Luego agregue el servicio MCP:

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

5. Verificar la instalación

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

Herramientas disponibles

Log-MCP proporciona las siguientes herramientas para que los asistentes de IA las invoquen:

list_servers

Lista la información de todos los servidores configurados.

Ejemplo de respuesta:

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

list_log_files

Lista los archivos de registro en el servidor especificado.

Parámetros:

server (opcional): Nombre del servidor de destino
level (opcional): Filtro de nivel de registro
startDate (opcional): Fecha de inicio (YYYY-MM-DD)
endDate (opcional): Fecha de fin (YYYY-MM-DD)

Ejemplo de respuesta:

{
  "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

Lee el contenido del archivo de registro especificado.

Parámetros:

filePath (obligatorio): Ruta relativa del archivo de registro
server (opcional): Nombre del servidor de destino
startLine (opcional): Número de línea inicial
endLine (opcional): Número de línea final
maxLines (opcional): Número máximo de líneas a leer

Ejemplo de respuesta:

{
  "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

Busca palabras clave en los archivos de registro.

Parámetros:

keyword (obligatorio): Palabra clave de búsqueda
server (opcional): Nombre del servidor de destino
levels (opcional): Matriz de niveles de registro, por defecto ["debug", "info"]
startDate (opcional): Fecha de inicio (YYYY-MM-DD)
endDate (opcional): Fecha de fin (YYYY-MM-DD)
useRegex (opcional): Si se utiliza expresión regular
contextLines (opcional): Número de líneas de contexto
maxResults (opcional): Número máximo de resultados

Ejemplo de respuesta:

{
  "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

Obtiene las líneas de registro más recientes.

Parámetros:

server (opcional): Nombre del servidor de destino
level (opcional): Nivel de registro, por defecto "info"
lines (opcional): Número de líneas, por defecto 50

Ejemplo de respuesta:

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

Configuración

Configuración del 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                  // 是否为默认服务器
}

Configuración del pool de conexiones SSH

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

Configuración predeterminada de consultas

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

Ejemplos de uso

En Claude Code, puede consultar registros directamente usando lenguaje natural:

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

搜索包含 "NullPointerException" 的日志

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

读取最新的 100 行 info 日志

Características de seguridad

Validación de parámetros - Todos los parámetros de entrada se validan estrictamente
Validación de rutas - Previene ataques de traversal de rutas
Escape de Shell - Todos los parámetros de comandos Shell se procesan con escape
Autenticación con clave privada SSH - Solo admite autenticación con archivo de clave privada SSH, no admite autenticación por contraseña, proporcionando mayor seguridad
Gestión del pool de conexiones - Gestiona automáticamente el ciclo de vida de las conexiones, previniendo fugas de recursos

Solución de problemas

Fallo de conexión SSH

Verifique los permisos de la clave privada SSH:

chmod 600 ~/id_rsa

Verifique la conexión SSH:

ssh -i ~/id_rsa root@192.168.5.169

Compruebe que las rutas en el archivo de configuración sean correctas

Archivo de registro no encontrado

Confirme que la configuración de logRootPath sea correcta
Compruebe si el formato de nombre del archivo de registro coincide con logFilePattern
Verifique que el archivo de registro exista en el servidor

El servicio MCP no responde

Compruebe si el servicio se inició correctamente
Revise la salida de registros para ver si hay mensajes de error
Verifique que la configuración de ~/.claude.json sea correcta

Pila tecnológica

Java 21 - Lenguaje de programación
Maven - Herramienta de construcción de proyectos
Apache MINA SSHD 2.12.0 - Cliente SSH
Jackson 2.17.0 - Serialización/deserialización JSON
Apache Commons Pool2 2.12.0 - Gestión del pool de conexiones
Undertow 2.3.12 - Servidor HTTP (modo HTTP)
SLF4J + Logback - Marco de registro

Estructura del proyecto

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 配置

Guía de contribución

¡Bienvenidos a enviar Issues y Pull Requests!

Haga fork de este repositorio
Cree una rama de características (git checkout -b feature/AmazingFeature)
Confirme los cambios (git commit -m 'Add some AmazingFeature')
Envíe a la rama (git push origin feature/AmazingFeature)
Envíe un Pull Request

Licencia

Este proyecto está bajo la Licencia Apache 2.0 - consulte el archivo LICENSE para más detalles

Final

Si le resulta útil, ¡no dude en dar una estrella (Star)! Si tiene sugerencias, por favor envíe un Issue. ¡Progresemos juntos!

Contacto

Autor: 小白菜
GitHub: https://github.com/caijianying