AI导哈

JSON日志分析服务器

一个用于读取和分析JSON格式日志文件的MCP服务器，提供搜索、过滤、聚合和分析结构化日志数据的功能。

  • by mfreeman451
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 mfreeman451/json-logs-mcp-server

使用说明

JSON日志MCP服务器

一种模型上下文协议（MCP）服务器，使Claude Desktop（或任何MCP客户端）能够读取和分析JSON格式的日志文件。此服务器提供用于搜索、过滤、聚合和分析结构化日志数据的工具。

特性

  • 📁 浏览日志文件 -列出并读取JSON格式的日志文件
  • 🔍 搜索和筛选 -按级别、模块、功能、消息内容和时间范围查询日志
  • 📊 综合数据 -根据各种标准对日志进行分组和分析
  • 📈 统计 -获取有关日志数据的全面统计信息
  • 🚀 快速高效 -针对处理大型日志文件进行了优化

先决条件

  • Python 3.11或更高版本
  • Claude Desktop（或其他MCP客户端）

安装

  1. 克隆此存储库：
git clone https://github.com/mfreeman451/json-logs-mcp-server.git
cd json-logs-mcp-server
  1. 创建虚拟环境：
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. 安装软件包：
pip install -e .
  1. 创建包装器脚本：
cat > run-json-logs-server.sh << 'EOF'
#!/bin/bash
cd "$(dirname "$0")"
source .venv/bin/activate
exec python json_logs_mcp_server.py
EOF
chmod +x run-json-logs-server.sh

配置

配置日志目录

默认情况下，服务器在 ./logs 相对于其运行位置的目录。您可以通过设置环境变量或编辑代码来更改此设置：

选项1：环境变量

export MCP_JSON_LOGS_DIR="/path/to/your/logs"

配置Claude桌面

将服务器添加到Claude Desktop配置文件中：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
  • Linux： ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "json-logs": {
      "command": "/absolute/path/to/run-json-logs-server.sh",
      "args": [],
      "env": {
        "MCP_JSON_LOGS_DIR": "/path/to/your/logs"
      }
    }
  }
}

重要：使用包装器脚本的绝对路径。

日志格式

服务器期望JSON日志文件每行包含一个JSON对象。每个日志条目应包括以下字段：

{
  "timestamp": "2024-01-15T10:30:45.123456",
  "level": "INFO",
  "message": "User authentication successful",
  "module": "auth.handler",
  "function": "authenticate_user",
  "line": 42
}

必填字段：

  • timestamp -ISO格式时间戳
  • level -日志级别（调试、信息、警告、错误、严重）
  • message -日志消息
  • module -模块名称
  • function -函数名称
  • line -线路编号

示例日志文件

创建一个名为的文件 example.log 使用以下内容测试服务器：

{"timestamp": "2024-01-15T10:30:45.123456", "level": "INFO", "message": "Application started successfully", "module": "main", "function": "startup", "line": 15}
{"timestamp": "2024-01-15T10:30:46.234567", "level": "DEBUG", "message": "Loading configuration from config.json", "module": "config.loader", "function": "load_config", "line": 42}
{"timestamp": "2024-01-15T10:30:47.345678", "level": "INFO", "message": "Database connection established", "module": "db.connection", "function": "connect", "line": 78}
{"timestamp": "2024-01-15T10:31:02.456789", "level": "WARNING", "message": "Rate limit approaching: 85% of quota used", "module": "api.ratelimit", "function": "check_limits", "line": 156}
{"timestamp": "2024-01-15T10:32:15.567890", "level": "ERROR", "message": "Failed to authenticate user: Invalid credentials", "module": "auth.handler", "function": "authenticate_user", "line": 203}
{"timestamp": "2024-01-15T10:32:16.678901", "level": "INFO", "message": "Retry attempt 1/3 for user authentication", "module": "auth.handler", "function": "retry_auth", "line": 215}
{"timestamp": "2024-01-15T10:33:45.789012", "level": "CRITICAL", "message": "Database connection lost: Connection timeout", "module": "db.connection", "function": "health_check", "line": 92}
{"timestamp": "2024-01-15T10:33:46.890123", "level": "INFO", "message": "Attempting database reconnection", "module": "db.connection", "function": "reconnect", "line": 105}
{"timestamp": "2024-01-15T10:33:48.901234", "level": "INFO", "message": "Database connection restored", "module": "db.connection", "function": "reconnect", "line": 112}
{"timestamp": "2024-01-15T10:35:22.012345", "level": "DEBUG", "message": "Cache hit for key: user_session_abc123", "module": "cache.manager", "function": "get", "line": 67}

Python记录器配置示例

以下是如何配置Python记录器以所需格式输出：

import logging
import json
from datetime import datetime

class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_obj = {
            "timestamp": datetime.fromtimestamp(record.created).isoformat(),
            "level": record.levelname,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
            "line": record.lineno
        }
        return json.dumps(log_obj)

# Configure logger
logger = logging.getLogger()
handler = logging.FileHandler('app.log')
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# Example usage
logger.info("Application started")
logger.error("Something went wrong")

可用工具

1.list_log_files

列出所有可用的日志文件及其元数据。

Claude中的示例用法：

  • “列出所有日志文件”
  • “显示可用日志”

2.查询日志

搜索和筛选日志条目。

参数：

  • files -要搜索的文件列表（可选，默认为全部）
  • level -按日志级别筛选
  • module -按模块名称筛选
  • function -按函数名称筛选
  • message_contains -在邮件内容中搜索
  • start_time -开始时间过滤器（ISO格式）
  • end_time -结束时间过滤器（ISO格式）
  • limit -最大结果（默认值：100）

Claude中的示例用法：

  • “显示今天以来的所有错误日志”
  • “查找包含‘数据库连接’的日志”
  • “显示过去一小时内身份验证模块的错误”
  • “搜索身份验证失败”

3.聚合日志

按指定条件聚合日志数据。

参数：

  • files -要分析的文件（可选）
  • group_by -分组标准：“级别”、“模块”、“功能”或“小时”

Claude中的示例用法：

  • “按级别对日志进行分组”
  • “显示哪些模块生成的日志最多”
  • “按小时分析日志分布”
  • “日志级别的细分是什么？”

4.get_log_stats

获取有关日志文件的全面统计信息。

Claude中的示例用法：

  • “显示日志统计信息”
  • “我的日志的总体摘要是什么？”
  • “我总共有多少个错误？”

使用示例

配置后，您可以通过Claude Desktop与日志交互：

示例1：查找错误

You: "Show me all ERROR and CRITICAL logs from the last hour"
Claude: I'll search for ERROR and CRITICAL level logs from the last hour...
[Uses query_logs tool with level and time filters]

示例2：分析模式

You: "Which module is generating the most warnings?"
Claude: Let me analyze the distribution of WARNING logs by module...
[Uses query_logs with level filter, then aggregate_logs grouped by module]

示例3：调试问题

You: "Find all database connection errors and show me what happened right before them"
Claude: I'll search for database connection errors and their context...
[Uses query_logs to find specific errors and surrounding log entries]

独立运行

您还可以独立运行服务器进行测试（MCP Inspector或其他MCP客户端）：

# With stdio transport (default)
python json_logs_mcp_server.py

故障排除

服务器无法启动

  • 检查是否安装了Python 3.8+： python3 --version
  • 确保安装了所有依赖项： pip install -e .
  • 验证日志目录是否存在并包含 .log 文件

“ENOENT Python 生成” error

  • 使用 python3 而不是 python 在您的配置中
  • 使用带有完整绝对路径的包装器脚本
  • 检查包装器脚本是否可执行： chmod +x run-json-logs-server.sh

“找不到模块”错误

  • 确保您使用的是激活虚拟环境的包装器脚本
  • 检查venv中是否安装了依赖项： source .venv/bin/activate && pip list
  • 重新安装依赖关系： pip install -e .

未找到日志

  • 验证配置的目录中是否存在日志文件
  • 检查日志文件是否具有 .log 扩展名（文件匹配 *.log* 已找到）
  • 确保日志文件采用正确的JSON格式（每行一个JSON对象）
  • 尝试使用上面提供的示例日志文件

工具未出现在Claude中

  • 配置更改后重新启动Claude Desktop
  • 查看Claude Desktop中的“连接应用程序”部分
  • 在Claude的开发人员控制台中查找错误消息
  • 确保服务器在Claude的UI中显示为“已连接”

调试提示

  • 手动运行服务器以查看任何错误消息： ./run-json-logs-server.sh
  • 检查服务器输出：通过stdio运行时，stderr上会显示诊断消息
  • 首先使用上述示例数据使用简单的日志文件进行测试
  • 验证JSON格式：每行必须是有效的JSON，并包含所有必填字段

性能注意事项

  • 服务器按需加载日志文件，而不是一次全部加载
  • 处理大型日志文件（>100MB）可能需要一些时间
  • 使用 limit 查询中用于控制结果大小的参数
  • 考虑轮换日志文件以保持性能

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

相关 MCP