localthink-mcp

Local LLM context compression for Claude Code. Offloads large file queries and document processing to Ollama so they never burn Claude's context window.

v0.1.0 benchmarked at ~30× token savings on 16 KB file queries. v1.1 adds 13 new tools covering every major token-waste pattern. v1.2 adds pre-injection: local_improve_prompt and local_preplan run locally before Claude sees the task — sharpening prompts and scaffolding plans so Claude executes rather than guesses. v2.1 adds smart buffer, execution filters, session scratchpad, persistent notes, response refinement, and a disk-backed result cache — 14 new tools, 45 total.

Quick start

# 1. Pull a model (once)
ollama pull qwen2.5:14b-instruct-q4_K_M

# 2. Register with Claude Code
claude mcp add localthink -- uvx localthink-mcp

# 3. Verify
claude mcp list   # localthink → Connected

Requirements

• Ollama installed and running (ollama serve)
• Claude Code CLI
• Python 3.10+

All 45 tools

v0.1.0 — Core compression

v1.1 — New routes

File operations

Composition (fewer round-trips)

Stateful document chat

Semantic & structural

Analysis / meta

v1.2 — Pre-injection (run before Claude thinks)

These tools run a local model pass before Claude engages with a task. Claude never sees the raw input — only the pre-processed output. Eliminates waste at the source rather than compressing after the fact.

local_improve_prompt example:

"make the auth faster"
→ local_improve_prompt(prompt, context="Next.js, JWT, DB bottleneck suspected")
→ "Optimise JWT validation latency in src/auth/middleware.ts — profile the verify()
   hot path, remove redundant DB round-trips, target p95 < 5 ms."
→ Feed that to Claude as the actual task

local_preplan example:

plan = local_preplan(
  task="add rate limiting to the API",
  context="Express.js, Redis available, routes in src/routes/",
  depth="standard"
)
# Returns: Goal / Assumptions / Steps with file paths / Risks / Open questions
# Then: "Execute this plan: <plan>"

v1.1 expansion — high-context compression + smart reading

High-context compression

Smart reading (avoid loading files at all)

Format transformation

Temporal & multi-file diff

v2.1 — Smart buffer, execution filters, scratchpad, notes, cache

Smart Buffer (raw output triage)

Execution Filters (project tools → local LLM)

Session Scratchpad (stateful decisions)

Persistent Notes (cross-session knowledge)

Response Quality & Cache

Decision guide

local_pipeline examples

# Extract auth sections, then summarize for security review
local_pipeline(text=big_doc, steps=[
    {"op": "extract",   "query": "authentication and authorization"},
    {"op": "summarize", "focus": "security risks and gotchas"},
])

# Answer a question after narrowing to the relevant section
local_pipeline(text=api_docs, steps=[
    {"op": "extract",  "query": "rate limiting"},
    {"op": "answer",   "question": "what headers control retry behaviour?"},
])

local_chat example

# Turn 1 — document is compressed automatically
r = local_chat(full_doc, "What does this library do?", "")
# r["doc"]     = compressed version (hold this)
# r["history"] = conversation so far (hold this)
# r["answer"]  = the answer

# Turn 2 — pass compressed doc + history back
r = local_chat(r["doc"], "How do I configure auth?", r["history"])

# Turn 3
r = local_chat(r["doc"], "Show me the relevant config keys", r["history"])

Configuration

The easiest way to configure LocalThink is to call local_config from Claude Code — it opens a GUI that covers every setting below.

Settings are saved to ~/.localthink-mcp/config.json and applied automatically on the next server start.

Ollama

Timeouts

Limits

Cache

Memo / Notes

Example: 3-tier model setup

{
  "mcpServers": {
    "localthink": {
      "env": {
        "OLLAMA_MODEL":      "qwen2.5:14b-instruct-q4_K_M",
        "OLLAMA_FAST_MODEL": "qwen2.5:7b-instruct-q4_K_M",
        "OLLAMA_TINY_MODEL": "qwen2.5:3b"
      }
    }
  }
}

Install options

uvx (recommended — zero setup)

claude mcp add localthink -- uvx localthink-mcp

pip

pip install localthink-mcp
claude mcp add localthink -- localthink-mcp

Windows — if uvx isn't on Claude's PATH

claude mcp add --transport stdio localthink -- cmd /c uvx localthink-mcp

Security

• Local only — runs as a stdio child process, never exposed to the network.
• local_answer / local_shrink_file / local_audit read any path your shell can access. Same trust level as Claude's built-in Read tool.
• Ollama has no auth by default. Don't expose port 11434 to the internet.
• No data leaves your machine. All inference is local.

Troubleshooting

[localthink] Ollama is not running

ollama serve
curl http://localhost:11434/api/tags

Slow responses Switch to a smaller model or set a fast model:

OLLAMA_MODEL=qwen2.5:7b-instruct claude

Windows: uvx not found Install uv, then retry. Or use cmd /c uvx fallback.

License

MIT © 2026 H3xabah