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:
- Create a virtual environment:
- Install the package:
- Create the wrapper script:
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
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
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:
Required Fields:
timestamp
- ISO format timestamplevel
- Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)message
- Log messagemodule
- Module namefunction
- Function nameline
- Line number
Sample Log File
Create a file named example.log
with the following content to test the server:
Python Logger Configuration Example
Here's how to configure a Python logger to output in the required format:
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 levelmodule
- Filter by module namefunction
- Filter by function namemessage_contains
- Search in message contentstart_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
Example 2: Analyzing Patterns
Example 3: Debugging Issues
Running Standalone
You can also run the server standalone for testing (MCP Inspector or other MCP clients):
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 ofpython
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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
JSON Logs MCP Server
Related MCP Servers
- Python
- JavaScriptMIT License
- PythonMIT License
- JavaScriptMIT License