🔍 Local Log & Observability Analyzer-MCP Server

Zero-cost · Fully local · No external APIs · Pure Python stdlib

• Turn raw log chaos into actionable insights. Point any MCP-compatible AI client at this server and ask natural questions like:
• "What's wrong with my app.log in the last 10 minutes?"
• "Are there any error bursts or anomalies in my syslog?"
• "Compare today's logs to yesterday's and tell me what changed."
• "Set an alert if OutOfMemory appears and check it now."

---

📦 Project Structure

log_analyzer_mcp/
├── server.py               ← MCP server (10 tools, pure stdlib)
├── generate_sample_logs.py ← Creates realistic test log files
├── test_client.py          ← CLI harness to call every tool directly
├── mcp_config.json         ← Paste-ready config for Claude Desktop / Cursor
└── README.md

---

🚀 Quick Start

1. Generate test logs (optional but recommended)

python generate_sample_logs.py
# Creates: sample_logs/app.log, syslog.log, access.log, app_v2.log

2. Optional — enable live system metrics

pip install psutil
# Without psutil the system_metrics tool falls back to /proc/meminfo (Linux only)

3. Test every tool from the CLI

python test_client.py tools           # list all 10 tools
python test_client.py summarize       # summarize app.log
python test_client.py scan            # scan last 200 lines
python test_client.py anomaly         # detect error bursts & spam
python test_client.py search  app.log "OutOfMemory"
python test_client.py compare app.log app_v2.log
python test_client.py report          # export Markdown report
python test_client.py metrics         # live CPU / RAM / disk
python test_client.py list    sample_logs/
python test_client.py alert-set  app.log "circuit breaker"
python test_client.py alert-check

4. Wire up to Claude Desktop (or any MCP client)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "log-analyzer": {
      "command": "python",
      "args": ["C:/Users/YourName/projects/log_analyzer_mcp/server.py"]
    }
  }
}

Restart Claude Desktop. The tools appear automatically.

---

🛠️ Available Tools (10)

Tool	What it does
scan_log	Parse last N lines — level counts, top errors, optional level filter
search_logs	Regex/text search with optional context lines before/after each match
summarize_log	Full narrative summary: health, error rate, top IPs, HTTP codes
anomaly_detect	Error bursts (sliding window), log spam, exception clusters
system_metrics	Live CPU %, RAM, disk usage, top processes (psutil or /proc)
list_logs	Discover all log files in a directory tree, sorted by newest
set_alert	Register a pattern-based alert on any log file
check_alerts	Fire-check all registered alerts against the current log tail
compare_logs	Side-by-side comparison of two log files — error delta + verdict
export_report	Generate and save a Markdown observability report

---

💡 Example AI Conversations (after wiring to Claude Desktop)

"Summarize my app.log and tell me if anything looks wrong."

Claude calls summarize_log → returns health status 🔴 Degraded, error rate 7.2%, circuit breaker OPEN messages.

"Search app.log for OutOfMemory with 2 lines of context."

Claude calls search_logs with context_lines=2 → returns every OOM line with surrounding context.

"Are there any anomalies? Set an alert for 'circuit breaker' and check it."

Claude chains anomaly_detect → set_alert → check_alerts in one turn.

"Compare app.log to app_v2.log and give me an error rate delta."

Claude calls compare_logs → verdict: "B is significantly worse (Δerr=+4.2%)"

"Export a full Markdown report for app.log."

Claude calls export_report → saves app.log.report.md to disk.

---

📋 Log Format Support

Automatically parses:

• ISO-8601 — 2026-03-17T19:54:39 [ERROR] ...
• Apache/Nginx CLF — 203.0.113.42 - - [17/Mar/2026:19:54:39] "GET /api" 500 ...
• Syslog — Mar 17 19:54:39 web01 sshd[1234]: ...
• Plain text — any file with ERROR/WARN/INFO/DEBUG keywords
• Gzipped logs — .log.gz files opened transparently

---

🔧 Extending the Server

Add a new tool in server.py in 3 steps:

# 1. Implement the function
def tool_my_tool(path: str) -> dict:
    return {"result": "..."}

# 2. Add to TOOLS dict
TOOLS["my_tool"] = {
    "fn": lambda args: tool_my_tool(args["path"]),
    "schema": {
        "name": "my_tool",
        "description": "Does something cool.",
        "inputSchema": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
}
# 3. Done — the MCP client picks it up automatically on next restart.

---

🏗️ Architecture

MCP Client (Claude Desktop / Cursor / Windsurf)
        ↕  JSON-RPC 2.0 over stdio
server.py
  ├── scan_log()        ← regex + level parser
  ├── search_logs()     ← full-file regex search
  ├── summarize_log()   ← Counter aggregation
  ├── anomaly_detect()  ← sliding-window burst detection
  ├── system_metrics()  ← psutil / /proc fallback
  ├── list_logs()       ← pathlib rglob
  ├── set/check_alert() ← in-memory alert store
  ├── compare_logs()    ← dual-summary + delta
  └── export_report()   ← Markdown writer

• No network calls. No API keys. No database. Restarts clean.

---

📄 License

MIT — free to use, fork, and extend.

Copyright (c) 2026 Deep Research Agent Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including, without limitation, the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🤝 Contributing

1. Fork this repo
2. Add a new tool or improve a parser
3. Update test_client.py with a matching command
4. Submit a PR with a sample log showing it working

---

Built with Python stdlib only. Inspired by the gap between "tail -f" and real observability.