Log-MCP

介绍

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

主要特性

• 多服务器支持 - 支持配置多个远程服务器，统一管理日志查询
• SSH 连接池 - 高效的 SSH 连接池管理，支持连接复用和自动重连
• 多种日志操作 - 支持列出日志文件、读取日志内容、搜索日志、实时查看日志尾部
• 灵活的传输模式 - 支持 HTTP 和 STDIO 两种传输模式，适配不同使用场景
• 安全性保障 - 参数验证、路径验证、Shell 转义等多重安全机制
• 日志级别过滤 - 支持按日志级别（info、warn、error、debug）过滤查询
• 正则表达式搜索 - 支持使用正则表达式进行日志内容搜索
• 上下文行显示 - 搜索结果可显示匹配行的上下文内容

实现原理及关键技术

• MCP 协议 - 实现 Model Context Protocol 规范，提供标准化的工具调用接口
• Apache MINA SSHD - 基于 Apache MINA SSHD 实现 SSH 连接和命令执行
• 连接池技术 - 使用 Apache Commons Pool2 实现 SSH 连接池管理
• 双传输模式 - 支持 Undertow HTTP Server 和 STDIO 两种传输方式
• JSON-RPC 2.0 - 基于 JSON-RPC 2.0 协议进行请求响应处理

运行环境

• JDK 21+
• Maven 3.6+
• SSH 私钥文件（用于连接远程服务器）

快速开始

1. 构建项目

cd log-mcp
mvn clean package

构建完成后，会在 target 目录下生成 log-mcp-1.0.0.jar 文件。

2. 配置服务器信息

编辑 src/main/resources/config.json 文件，配置远程服务器信息：

{
  "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. 配置 SSH 认证

Log-MCP 目前支持 SSH 私钥文件认证方式连接远程服务器。

SSH 私钥认证

1. 生成 SSH 密钥对（如果还没有）：

ssh-keygen -t rsa -b 4096 -C "[email protected]"

2. 将公钥添加到远程服务器：

ssh-copy-id -i ~/.ssh/id_rsa.pub [email protected]

或手动将公钥内容追加到远程服务器的 ~/.ssh/authorized_keys 文件中。

3. 确保私钥文件权限正确：

chmod 600 ~/.ssh/id_rsa

4. 验证 SSH 连接：

ssh -i ~/.ssh/id_rsa [email protected]

注意事项：

• 私钥文件路径在配置文件中通过 privateKeyPath 字段指定
• 支持使用环境变量，如 ${ssh.cert.path}
• 确保私钥文件格式正确（支持 OpenSSH 和 PEM 格式）
• 目前不支持密码认证方式，仅支持私钥文件认证

4. 添加 MCP 服务

方式一：STDIO 模式（推荐）

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

方式二：HTTP 模式

先启动 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

然后添加 MCP 服务：

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

5. 验证安装

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

可用工具

Log-MCP 提供以下工具供 AI 助手调用：

list_servers

列出所有配置的服务器信息。

返回示例：

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

list_log_files

列出指定服务器上的日志文件。

参数：

• server (可选): 目标服务器名称
• level (可选): 日志级别过滤
• startDate (可选): 开始日期 (YYYY-MM-DD)
• endDate (可选): 结束日期 (YYYY-MM-DD)

返回示例：

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

读取指定日志文件的内容。

参数：

• filePath (必需): 日志文件相对路径
• server (可选): 目标服务器名称
• startLine (可选): 起始行号
• endLine (可选): 结束行号
• maxLines (可选): 最大读取行数

返回示例：

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

在日志文件中搜索关键词。

参数：

• keyword (必需): 搜索关键词
• server (可选): 目标服务器名称
• levels (可选): 日志级别数组，默认 ["debug", "info"]
• startDate (可选): 开始日期 (YYYY-MM-DD)
• endDate (可选): 结束日期 (YYYY-MM-DD)
• useRegex (可选): 是否使用正则表达式
• contextLines (可选): 上下文行数
• maxResults (可选): 最大结果数

返回示例：

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

获取最新的日志行。

参数：

• server (可选): 目标服务器名称
• level (可选): 日志级别，默认 "info"
• lines (可选): 行数，默认 50

返回示例：

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

配置说明

服务器配置

{
  "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                  // 是否为默认服务器
}

SSH 连接池配置

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

查询默认配置

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

使用示例

在 Claude Code 中，你可以直接使用自然语言查询日志：

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

搜索包含 "NullPointerException" 的日志

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

读取最新的 100 行 info 日志

安全特性

• 参数验证 - 所有输入参数都经过严格验证
• 路径验证 - 防止路径遍历攻击
• Shell 转义 - 所有 Shell 命令参数都经过转义处理
• SSH 私钥认证 - 仅支持 SSH 私钥文件认证，不支持密码认证，提供更高的安全性
• 连接池管理 - 自动管理连接生命周期，防止资源泄漏

故障排查

SSH 连接失败

1. 检查 SSH 私钥权限：

chmod 600 ~/id_rsa

2. 验证 SSH 连接：

ssh -i ~/id_rsa [email protected]

3. 检查配置文件中的路径是否正确

日志文件找不到

1. 确认 logRootPath 配置正确
2. 检查日志文件命名格式是否匹配 logFilePattern
3. 验证服务器上日志文件是否存在

MCP 服务未响应

1. 检查服务是否正常启动
2. 查看日志输出是否有错误信息
3. 验证 ~/.claude.json 配置是否正确

技术栈

• Java 21 - 编程语言
• Maven - 项目构建工具
• Apache MINA SSHD 2.12.0 - SSH 客户端
• Jackson 2.17.0 - JSON 序列化/反序列化
• Apache Commons Pool2 2.12.0 - 连接池管理
• Undertow 2.3.12 - HTTP 服务器（HTTP 模式）
• SLF4J + Logback - 日志框架

项目结构

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

贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

许可证

本项目采用 Apache License 2.0 许可证 - 详见 LICENSE 文件

最后

若觉得有方便到您，欢迎 Star 哦。若有建议，请提 Issue。大家共同进步！

联系方式

• 作者：小白菜
• GitHub：https://github.com/caijianying