{"id":29114496,"url":"https://github.com/mfreeman451/json-logs-mcp-server","last_synced_at":"2026-02-26T21:36:00.528Z","repository":{"id":301874263,"uuid":"996989879","full_name":"mfreeman451/json-logs-mcp-server","owner":"mfreeman451","description":"MCP server for Python JSON logs","archived":false,"fork":false,"pushed_at":"2025-06-06T02:47:19.000Z","size":33,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T20:33:37.564Z","etag":null,"topics":["json","logs","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfreeman451.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-05T19:19:49.000Z","updated_at":"2025-08-24T15:02:29.000Z","dependencies_parsed_at":"2025-06-29T11:19:36.518Z","dependency_job_id":null,"html_url":"https://github.com/mfreeman451/json-logs-mcp-server","commit_stats":null,"previous_names":["mfreeman451/json-logs-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mfreeman451/json-logs-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfreeman451%2Fjson-logs-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfreeman451%2Fjson-logs-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfreeman451%2Fjson-logs-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfreeman451%2Fjson-logs-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfreeman451","download_url":"https://codeload.github.com/mfreeman451/json-logs-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfreeman451%2Fjson-logs-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29873313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T21:05:00.265Z","status":"ssl_error","status_checked_at":"2026-02-26T20:57:13.669Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","logs","mcp","mcp-server"],"created_at":"2025-06-29T11:06:26.065Z","updated_at":"2026-02-26T21:36:00.505Z","avatar_url":"https://github.com/mfreeman451.png","language":"Python","funding_links":[],"categories":["Monitoring","🤖 AI/ML"],"sub_categories":["How to Submit"],"readme":"# JSON Logs MCP Server\n\nA 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.\n\n## Features\n\n- 📁 **Browse log files** - List and read JSON-formatted log files\n- 🔍 **Search and filter** - Query logs by level, module, function, message content, and time range\n- 📊 **Aggregate data** - Group and analyze logs by various criteria\n- 📈 **Statistics** - Get comprehensive statistics about your log data\n- 🚀 **Fast and efficient** - Optimized for handling large log files\n\n## Prerequisites\n\n- Python 3.11 or higher\n- Claude Desktop (or another MCP client)\n\n## Installation\n\n1. Clone this repository:\n```bash\ngit clone https://github.com/mfreeman451/json-logs-mcp-server.git\ncd json-logs-mcp-server\n```\n\n2. Create a virtual environment:\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n```\n\n3. Install the package:\n```bash\npip install -e .\n```\n\n4. Create the wrapper script:\n```bash\ncat \u003e run-json-logs-server.sh \u003c\u003c 'EOF'\n#!/bin/bash\ncd \"$(dirname \"$0\")\"\nsource .venv/bin/activate\nexec python json_logs_mcp_server.py\nEOF\nchmod +x run-json-logs-server.sh\n```\n\n## Configuration\n\n### Configure Log Directory\n\nBy 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:\n\n**Option 1: Environment Variable**\n```bash\nexport MCP_JSON_LOGS_DIR=\"/path/to/your/logs\"\n```\n\n### Configure Claude Desktop\n\nAdd the server to your Claude Desktop configuration file:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"json-logs\": {\n      \"command\": \"/absolute/path/to/run-json-logs-server.sh\",\n      \"args\": [],\n      \"env\": {\n        \"MCP_JSON_LOGS_DIR\": \"/path/to/your/logs\"\n      }\n    }\n  }\n}\n```\n\n**Important**: Use the absolute path to the wrapper script.\n\n## Log Format\n\nThe server expects JSON log files with one JSON object per line. Each log entry should include these fields:\n\n```json\n{\n  \"timestamp\": \"2024-01-15T10:30:45.123456\",\n  \"level\": \"INFO\",\n  \"message\": \"User authentication successful\",\n  \"module\": \"auth.handler\",\n  \"function\": \"authenticate_user\",\n  \"line\": 42\n}\n```\n\n### Required Fields:\n- `timestamp` - ISO format timestamp\n- `level` - Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n- `message` - Log message\n- `module` - Module name\n- `function` - Function name\n- `line` - Line number\n\n### Sample Log File\n\nCreate a file named `example.log` with the following content to test the server:\n\n```json\n{\"timestamp\": \"2024-01-15T10:30:45.123456\", \"level\": \"INFO\", \"message\": \"Application started successfully\", \"module\": \"main\", \"function\": \"startup\", \"line\": 15}\n{\"timestamp\": \"2024-01-15T10:30:46.234567\", \"level\": \"DEBUG\", \"message\": \"Loading configuration from config.json\", \"module\": \"config.loader\", \"function\": \"load_config\", \"line\": 42}\n{\"timestamp\": \"2024-01-15T10:30:47.345678\", \"level\": \"INFO\", \"message\": \"Database connection established\", \"module\": \"db.connection\", \"function\": \"connect\", \"line\": 78}\n{\"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}\n{\"timestamp\": \"2024-01-15T10:32:15.567890\", \"level\": \"ERROR\", \"message\": \"Failed to authenticate user: Invalid credentials\", \"module\": \"auth.handler\", \"function\": \"authenticate_user\", \"line\": 203}\n{\"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}\n{\"timestamp\": \"2024-01-15T10:33:45.789012\", \"level\": \"CRITICAL\", \"message\": \"Database connection lost: Connection timeout\", \"module\": \"db.connection\", \"function\": \"health_check\", \"line\": 92}\n{\"timestamp\": \"2024-01-15T10:33:46.890123\", \"level\": \"INFO\", \"message\": \"Attempting database reconnection\", \"module\": \"db.connection\", \"function\": \"reconnect\", \"line\": 105}\n{\"timestamp\": \"2024-01-15T10:33:48.901234\", \"level\": \"INFO\", \"message\": \"Database connection restored\", \"module\": \"db.connection\", \"function\": \"reconnect\", \"line\": 112}\n{\"timestamp\": \"2024-01-15T10:35:22.012345\", \"level\": \"DEBUG\", \"message\": \"Cache hit for key: user_session_abc123\", \"module\": \"cache.manager\", \"function\": \"get\", \"line\": 67}\n```\n\n### Python Logger Configuration Example\n\nHere's how to configure a Python logger to output in the required format:\n\n```python\nimport logging\nimport json\nfrom datetime import datetime\n\nclass JSONFormatter(logging.Formatter):\n    def format(self, record):\n        log_obj = {\n            \"timestamp\": datetime.fromtimestamp(record.created).isoformat(),\n            \"level\": record.levelname,\n            \"message\": record.getMessage(),\n            \"module\": record.module,\n            \"function\": record.funcName,\n            \"line\": record.lineno\n        }\n        return json.dumps(log_obj)\n\n# Configure logger\nlogger = logging.getLogger()\nhandler = logging.FileHandler('app.log')\nhandler.setFormatter(JSONFormatter())\nlogger.addHandler(handler)\nlogger.setLevel(logging.INFO)\n\n# Example usage\nlogger.info(\"Application started\")\nlogger.error(\"Something went wrong\")\n```\n\n## Available Tools\n\n### 1. list_log_files\nLists all available log files with metadata.\n\n**Example usage in Claude:**\n- \"List all log files\"\n- \"Show me available logs\"\n\n### 2. query_logs\nSearch and filter log entries.\n\n**Parameters:**\n- `files` - List of files to search (optional, defaults to all)\n- `level` - Filter by log level\n- `module` - Filter by module name\n- `function` - Filter by function name\n- `message_contains` - Search in message content\n- `start_time` - Start time filter (ISO format)\n- `end_time` - End time filter (ISO format)\n- `limit` - Maximum results (default: 100)\n\n**Example usage in Claude:**\n- \"Show me all ERROR logs from today\"\n- \"Find logs containing 'database connection'\"\n- \"Show errors from the auth module in the last hour\"\n- \"Search for authentication failures\"\n\n### 3. aggregate_logs\nAggregate log data by specified criteria.\n\n**Parameters:**\n- `files` - Files to analyze (optional)\n- `group_by` - Grouping criteria: \"level\", \"module\", \"function\", or \"hour\"\n\n**Example usage in Claude:**\n- \"Group logs by level\"\n- \"Show me which modules generate the most logs\"\n- \"Analyze log distribution by hour\"\n- \"What's the breakdown of log levels?\"\n\n### 4. get_log_stats\nGet comprehensive statistics about log files.\n\n**Example usage in Claude:**\n- \"Show me log statistics\"\n- \"What's the overall summary of my logs?\"\n- \"How many errors do I have total?\"\n\n## Usage Examples\n\nOnce configured, you can interact with your logs through Claude Desktop:\n\n### Example 1: Finding Errors\n```\nYou: \"Show me all ERROR and CRITICAL logs from the last hour\"\nClaude: I'll search for ERROR and CRITICAL level logs from the last hour...\n[Uses query_logs tool with level and time filters]\n```\n\n### Example 2: Analyzing Patterns\n```\nYou: \"Which module is generating the most warnings?\"\nClaude: Let me analyze the distribution of WARNING logs by module...\n[Uses query_logs with level filter, then aggregate_logs grouped by module]\n```\n\n### Example 3: Debugging Issues\n```\nYou: \"Find all database connection errors and show me what happened right before them\"\nClaude: I'll search for database connection errors and their context...\n[Uses query_logs to find specific errors and surrounding log entries]\n```\n\n## Running Standalone\n\nYou can also run the server standalone for testing (MCP Inspector or other MCP clients):\n\n```bash\n# With stdio transport (default)\npython json_logs_mcp_server.py\n```\n\n## Troubleshooting\n\n### Server won't start\n- Check that Python 3.8+ is installed: `python3 --version`\n- Ensure all dependencies are installed: `pip install -e .`\n- Verify the log directory exists and contains `.log` files\n\n### \"spawn python ENOENT\" error\n- Use `python3` instead of `python` in your configuration\n- Use the wrapper script with the full absolute path\n- Check that the wrapper script is executable: `chmod +x run-json-logs-server.sh`\n\n### \"Module not found\" errors\n- Make sure you're using the wrapper script that activates the virtual environment\n- Check that dependencies are installed in the venv: `source .venv/bin/activate \u0026\u0026 pip list`\n- Reinstall dependencies: `pip install -e .`\n\n### No logs found\n- Verify log files exist in the configured directory\n- Check that log files have `.log` extension (files matching `*.log*` are found)\n- Ensure log files are in the correct JSON format (one JSON object per line)\n- Try with the sample log file provided above\n\n### Tools not appearing in Claude\n- Restart Claude Desktop after configuration changes\n- Check the \"Connect Apps\" section in Claude Desktop\n- Look for error messages in Claude's developer console\n- Ensure the server shows as \"Connected\" in Claude's UI\n\n### Debugging tips\n- Run the server manually to see any error messages: `./run-json-logs-server.sh`\n- Check server output: When running via stdio, diagnostic messages appear on stderr\n- Test with a simple log file first using the sample data above\n- Verify JSON format: Each line must be valid JSON with all required fields\n\n## Performance Considerations\n\n- The server loads log files on-demand, not all at once\n- Large log files (\u003e100MB) may take a moment to process\n- Use the `limit` parameter in queries to control result size\n- Consider rotating log files to maintain performance\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfreeman451%2Fjson-logs-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfreeman451%2Fjson-logs-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfreeman451%2Fjson-logs-mcp-server/lists"}