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

Clone this repository:

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

Create a virtual environment:

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

Install the package:

pip install -e .

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:

timestamp - ISO format timestamp
level - Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
message - Log message
module - Module name
function - Function name
line - Line number

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:

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

Available Tools

1. list_log_files

Lists all available log files with metadata.

Example usage in Claude:

"List all log files"
"Show me available logs"

2. query_logs

Search and filter log entries.

Parameters:

files - List of files to search (optional, defaults to all)
level - Filter by log level
module - Filter by module name
function - Filter by function name
message_contains - Search in message content
start_time - Start time filter (ISO format)
end_time - End time filter (ISO format)
limit - Maximum results (default: 100)

Example usage in Claude:

"Show me all ERROR logs from today"
"Find logs containing 'database connection'"
"Show errors from the auth module in the last hour"
"Search for authentication failures"

3. aggregate_logs

Aggregate log data by specified criteria.

Parameters:

files - Files to analyze (optional)
group_by - Grouping criteria: "level", "module", "function", or "hour"

Example usage in Claude:

"Group logs by level"
"Show me which modules generate the most logs"
"Analyze log distribution by hour"
"What's the breakdown of log levels?"

4. get_log_stats

Get comprehensive statistics about log files.

Example usage in Claude:

"Show me log statistics"
"What's the overall summary of my logs?"
"How many errors do I have total?"

Usage Examples

Once configured, you can interact with your logs through Claude Desktop:

Example 1: Finding Errors

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]

Example 2: Analyzing Patterns

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]

Example 3: Debugging Issues

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]

Running Standalone

You can also run the server standalone for testing (MCP Inspector or other MCP clients):

# With stdio transport (default)
python json_logs_mcp_server.py

Troubleshooting

Server won't start

Check that Python 3.8+ is installed: python3 --version
Ensure all dependencies are installed: pip install -e .
Verify the log directory exists and contains .log files

"spawn python ENOENT" error

Use python3 instead of python in your configuration
Use the wrapper script with the full absolute path
Check that the wrapper script is executable: chmod +x run-json-logs-server.sh

"Module not found" errors

Make sure you're using the wrapper script that activates the virtual environment
Check that dependencies are installed in the venv: source .venv/bin/activate && pip list
Reinstall dependencies: pip install -e .

No logs found

Verify log files exist in the configured directory
Check that log files have .log extension (files matching *.log* are found)
Ensure log files are in the correct JSON format (one JSON object per line)
Try with the sample log file provided above

Tools not appearing in Claude

Restart Claude Desktop after configuration changes
Check the "Connect Apps" section in Claude Desktop
Look for error messages in Claude's developer console
Ensure the server shows as "Connected" in Claude's UI

Debugging tips

Run the server manually to see any error messages: ./run-json-logs-server.sh
Check server output: When running via stdio, diagnostic messages appear on stderr
Test with a simple log file first using the sample data above
Verify JSON format: Each line must be valid JSON with all required fields

Performance Considerations

The server loads log files on-demand, not all at once
Large log files (>100MB) may take a moment to process
Use the limit parameter in queries to control result size
Consider rotating log files to maintain performance

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

JSON Logs MCP Server