JSON Logs MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop (or any MCP client) to read and analyze JSON-formatted log files. This server provides tools for searching, filtering, aggregating, and analyzing structured log data.

Features

- 📁 Browse log files - List and read JSON-formatted log files
- 🔍 Search and filter - Query logs by level, module, function, message content, and time range
- 📊 Aggregate data - Group and analyze logs by various criteria
- 📈 Statistics - Get comprehensive statistics about your log data
- 🚀 Fast and efficient - Optimized for handling large log files

Prerequisites

- Python 3.11 or higher
- Claude Desktop (or another MCP client)

Installation

1. Clone this repository:

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

cd json-logs-mcp-server

2. Create a virtual environment:

python3 -m venv .venv

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

3. Install the package:

pip install -e .

4. Create the wrapper script:

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

Configuration

Configure Log Directory

By default, the server looks for logs in the ./logs directory relative to where it's run. You can change this by setting an environment variable or editing the code:

Option 1: Environment Variable

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

Configure Claude Desktop

Add the server to your Claude Desktop configuration file:
- 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"
      }
    }
  }
}

Important: Use the absolute path to the wrapper script.

Log Format

The server expects JSON log files with one JSON object per line. Each log entry should include these fields:

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

Required Fields:

Sample Log File

Create a file named example.log with the following content to test the server:

{"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 Logger Configuration Example

Here's how to configure a Python logger to output in the required format:

```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)