json-logs

This MCP server provides tools to browse, search, filter, and analyze JSON-formatted log files so Claude Desktop (or any MCP client) can interact with your logs in a structured way. You can list available log files, run targeted queries by level, module, function, and text content, and perform aggregations or statistics to understand logging patterns. The server expects one JSON object per line in each log file and supports common log fields such as timestamp, level, message, module, function, and line. Use Claude to invoke the available tools to find errors, inspect specific modules, or study trends over time. Tools include list_log_files for discovery, query_logs for filtered searches, aggregate_logs for grouping results, and get_log_stats for overall summaries.

Prerequisites

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

Installation steps

1. Clone the repository and enter the project directory:

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

2. Create a virtual environment and activate it:

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

3. Install the package in editable mode:

pip install -e .

4. Create the wrapper script to run the server (optional if you run directly):

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

5. Run the server directly for testing (standalone mode):

python json_logs_mcp_server.py

Tips and common guidance:

• Environment variable for log location: MCP_JSON_LOGS_DIR can be set to point to your JSON log files directory (default is ./logs if not set).
• When configuring Claude Desktop, always provide absolute path to the wrapper script or the Python entry point as shown in the README to avoid path issues.
• Logs must be JSON objects per line with fields: timestamp, level, message, module, function, and line. Use the provided sample format to test.
• Ensure Python 3.11+ is installed and that the virtual environment is activated when running the server to guarantee dependencies are resolved.
• If you add new log fields, consider updating any downstream tooling or queries to accommodate them.