JSON Logs MCP Server

JSON Logs 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

2. 创建虚拟环境：

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

3. 安装软件包：

pip install -e .

4. 创建包装脚本：

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)

# 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. query_logs

搜索和筛选日志条目。

参数：

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

在 Claude 中的用法示例：

• “显示今天所有的 ERROR 日志”
• “查找包含‘database connection’的日志”
• “显示过去一小时 auth 模块中的错误”
• “搜索身份验证失败”

3. aggregate_logs

按指定条件汇总日志数据。

参数：

• files - 要分析的文件（可选）
• group_by - 分组条件：“level”、“module”、“function”或“hour”

在 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 文件

“spawn python ENOENT”错误

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

“Module not found”错误

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

未找到日志

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

Claude 中未显示工具

• 更改配置后重启 Claude Desktop
• 检查 Claude Desktop 中的“Connect Apps”部分
• 查看 Claude 的开发者控制台中是否有错误消息
• 确认 Claude 界面中服务显示为“Connected”

调试提示

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

性能注意事项

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

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT License — 详情请参阅 LICENSE 文件