Json Logs MCP Server

🚀 JSON日志MCP服务器

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

🚀 快速开始

JSON日志MCP服务器允许Claude Desktop（或任何MCP客户端）读取和分析JSON格式的日志文件。以下是使用该服务器的基本步骤：

1. 确保你已经安装了Python 3.11或更高版本，并且拥有Claude Desktop（或其他MCP客户端）。
2. 按照安装指南进行安装和配置。
3. 配置日志目录和Claude Desktop。
4. 按照日志格式要求生成或准备日志文件。
5. 通过Claude Desktop使用可用的工具与日志进行交互。

✨ 主要特性

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

📦 安装指南

克隆仓库

git clone https://github.com/mfreeman451/json-logs-mcp-server.git
cd json-logs-mcp-server

创建虚拟环境

python3 -m venv .venv
source .venv/bin/activate  # 在Windows上: .venv\Scripts\activate

安装包

pip install -e .

创建包装脚本

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 Desktop

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

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %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 - 日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• 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)

# 配置日志记录器
logger = logging.getLogger()
handler = logging.FileHandler('app.log')
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# 示例用法
logger.info("Application started")
logger.error("Something went wrong")

可用工具

1. list_log_files

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

在Claude中的示例用法：

• "列出所有日志文件"
• "显示可用的日志"

2. query_logs

搜索和过滤日志条目。

参数：

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

在Claude中的示例用法：

• "显示今天所有的ERROR日志"
• "查找包含'数据库连接'的日志"
• "显示过去一小时内auth模块的错误"
• "搜索认证失败的日志"

3. aggregate_logs

按指定标准聚合日志数据。

参数：

• files - 要分析的文件（可选）
• group_by - 分组标准："level"、"module"、"function" 或 "hour"

在Claude中的示例用法：

• "按级别分组日志"
• "显示哪个模块生成的日志最多"
• "按小时分析日志分布"
• "日志级别的分布情况如何？"

4. get_log_stats

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

在Claude中的示例用法：

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

💻 使用示例

示例1：查找错误

你: "显示过去一小时内所有的ERROR和CRITICAL日志"
Claude: 我将搜索过去一小时内的ERROR和CRITICAL级别日志...
[使用query_logs工具进行级别和时间过滤]

示例2：分析模式

你: "哪个模块生成的警告最多？"
Claude: 让我按模块分析WARNING日志的分布...
[使用带有级别过滤的query_logs，然后按模块分组使用aggregate_logs]

示例3：调试问题

你: "查找所有数据库连接错误，并显示错误发生前的情况"
Claude: 我将搜索数据库连接错误及其上下文...
[使用query_logs查找特定错误和周围的日志条目]

独立运行

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

# 使用标准输入输出传输（默认）
python json_logs_mcp_server.py

🔧 技术细节

性能考虑

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

故障排除

服务器无法启动

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

"spawn python ENOENT"错误

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

"Module not found"错误

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

未找到日志

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

工具未在Claude中显示

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

调试提示

• 手动运行服务器以查看任何错误消息：./run-json-logs-server.sh。
• 检查服务器输出：通过标准输入输出运行时，诊断消息将显示在标准错误输出中。
• 首先使用上面的示例数据测试一个简单的日志文件。
• 验证JSON格式：每行必须是包含所有必需字段的有效JSON。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。