log-context-mcp

Stop dumping raw logs into your AI agent's context window.

cat error.log | claude on a 5000-line log burns 15,000+ tokens on repeated health checks, INFO spam, and boilerplate — before the agent finds the 3 lines that matter. This MCP server preprocesses logs first, hands the agent a structured ~1000 token summary, and lets it drill into raw lines only when needed.

Benchmark: 2,000-line Apache log → 70 unique lines (96.5% reduction). Root cause correctly identified: mod_jk worker instability from a cyclic init/failure pattern.

How it works

Raw log (5000 lines)
      │
      ▼
┌─────────────────────────────────────────┐
│  Layer 1 — Deterministic (free)         │
│  • Dedup lines, count occurrences       │
│  • Detect severity (FATAL/ERROR/WARN…)  │
│  • Group stack traces                   │
│  • Strip ANSI, timestamps, noise        │
│  → typically 50–95% reduction           │
└────────────────────┬────────────────────┘
                     │ ~1000 token summary
                     ▼
┌─────────────────────────────────────────┐
│  Layer 2 — Semantic (cheap/optional)    │
│  • Root cause in 1–2 sentences          │
│  • Error classification & timeline      │
│  • Flags lines needing attention        │
└────────────────────┬────────────────────┘
                     │
                     ▼
             Agent sees summary
             + drills into raw lines
               on demand (Layer 3)

Install

Quickest — the setup script handles everything:

pip install log-context-mcp
curl -fsSL https://raw.githubusercontent.com/lorenzoc25/log-context-mcp/main/scripts/setup.sh | bash

It registers the MCP server, optionally configures semantic analysis, installs the /analyze-log skill + log-analyzer Haiku agent, and updates ~/.claude/CLAUDE.md so Claude automatically uses log_ingest when it sees a log file.

# 1. Install
pip install log-context-mcp

# 2. Register MCP server (deterministic only — no API key needed)
claude mcp add log-context -- log-context-mcp

# 3. Enable semantic analysis — pick one backend:
#    Gemini/Gemma (free tier): https://aistudio.google.com/apikey
claude mcp add log-context \
  -e OPENAI_API_KEY=<gemini-key> \
  -e OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai \
  -e LOG_CONTEXT_MODEL=gemma-3-27b-it \
  -- log-context-mcp

#    Anthropic
claude mcp add log-context -e ANTHROPIC_API_KEY=<key> -- log-context-mcp

#    OpenAI / Groq / Together / any OpenAI-compatible provider
claude mcp add log-context \
  -e OPENAI_API_KEY=<key> \
  -e OPENAI_BASE_URL=<base-url> \
  -e LOG_CONTEXT_MODEL=<model> \
  -- log-context-mcp

#    Ollama (local)
claude mcp add log-context -e LOG_CONTEXT_MODEL=llama3 -- log-context-mcp

# 4. Install the /analyze-log skill + Haiku agent (Option B — no external API)
mkdir -p ~/.claude/commands ~/.claude/agents
curl -fsSL https://raw.githubusercontent.com/lorenzoc25/log-context-mcp/main/skills/analyze-log.md \
  -o ~/.claude/commands/analyze-log.md
curl -fsSL https://raw.githubusercontent.com/lorenzoc25/log-context-mcp/main/.claude/agents/log-analyzer.md \
  -o ~/.claude/agents/log-analyzer.md

# 5. Auto-trigger: add to ~/.claude/CLAUDE.md
cat >> ~/.claude/CLAUDE.md << 'EOF'

## Log Analysis
When analyzing log files or log output, always use the `log_ingest` MCP tool instead of reading the file directly. Call `log_ingest` with `file_path=` and `enable_semantic=false`, then analyze the preprocessed summary yourself. Use `log_get_lines` to drill into specific patterns.
EOF

Semantic analysis: two approaches

Layer 1 is always free and runs locally. For semantic analysis (root cause, timeline, classification), choose one:

Option A — External LLM

A dedicated cheap model analyzes the compressed summary. Runs automatically on every log_ingest call. The setup script configures this interactively.

OPENAI_API_KEY is used for all OpenAI-compatible providers. Set OPENAI_BASE_URL to point to your provider.

Option B — /analyze-log skill

Layer 1 compresses the log, then the skill spins up a dedicated log-analyzer sub-agent running on Haiku to do semantic analysis. No separate API key needed beyond your existing Claude subscription.

/analyze-log /path/to/your.log

The log-analyzer agent is defined in .claude/agents/log-analyzer.md with model: haiku — cheap, fast, and isolated from your main conversation context.

Both options produce equivalent output. Option A runs automatically on every log_ingest; Option B is explicit and uses Haiku via your subscription.

Usage

Once installed, just talk to Claude normally — it calls log_ingest automatically:

look at /tmp/error.log
why is my build failing? here's the output: [paste]
debug this crash dump: /var/log/app/crash.log

To drill into specific lines after ingestion:

show me the ConnectionRefused lines
what's around line 847?

MCP tools

log_ingest parameters: file_path, log_text, label (default: "default"), enable_semantic (default: true).

log_get_lines parameters: pattern (regex), severity, max_lines (default: 30), around_line, context_lines (default: 5).

Environment variables

License

MIT