3 tools. Zero friction. Maximum token savings.
Distill is an open-source MCP server that optimizes LLM token usage through intelligent context compression. 3 always-loaded tools replace dozens of individual calls. Works with Claude Code, Cursor, and Windsurf.
Claude Code already compresses context after it enters the window. Distill compresses before — catching large outputs at the source.
| Problem | Distill Tool | How | Savings |
|---|---|---|---|
| Large build output, logs, diffs | auto_optimize |
Auto-detects type, applies best compressor | 40-95% |
| Reading entire files for one function | smart_file_read |
AST extraction for 7 languages | 50-90% |
| Chaining 5-10 tool calls | code_execute |
TypeScript SDK in sandbox — one call | 98% |
Before: 5 tool calls (Read + Grep + Read + Read + compress) = ~2,500 tokens overhead
After: 1 code_execute call = ~500 tokens overhead
# Run directly with npx
npx distill-mcp
# Or install globally
npm install -g distill-mcp
# Auto-configure your IDE
distill-mcp setupclaude mcp add distill -- npx distill-mcpAll 3 tools are available immediately — no discovery step, no loading modes.
Auto-detects content type and applies the optimal compression strategy.
| Strategy | Content Type | Typical Savings |
|---|---|---|
build |
Compiler errors (tsc, rustc, webpack) | 95% |
logs |
Server/test/build logs | 80-90% |
errors |
Repeated error lines | 70-90% |
diff |
Git diffs | 60-80% |
stacktrace |
Stack traces | 50-80% |
code / semantic |
Source code (TF-IDF) | 40-60% |
config |
JSON/YAML configs | 30-60% |
auto |
Auto-detect best strategy | varies |
auto_optimize content="<large build output>" strategy="auto"
Read code with precision — extract exactly what you need.
5 modes:
skeleton— Function/class signatures only (depth 1-3)extract— Pull a specific function, class, or interface by namesearch— Find elements matching a queryfull— Complete file structure overviewauto— Detect mode from params
7 languages: TypeScript, JavaScript, Python, Go, Rust, PHP, Swift
smart_file_read filePath="src/server.ts" mode="skeleton"
smart_file_read filePath="src/server.ts" mode="extract" target={"type":"function","name":"createServer"}
smart_file_read filePath="src/server.ts" mode="search" query="register"
Write TypeScript instead of chaining tool calls. Access files, git, search, and compress via the ctx.* SDK.
code_execute code="return ctx.compress.auto(ctx.files.read('build.log'))"
Batch multiple operations in one call:
// Read 3 files, extract key functions, compress the result — 1 tool call instead of 7
const files = ["src/server.ts", "src/registry.ts", "src/executor.ts"];
const skeletons = files.map(f => ctx.code.skeleton(ctx.files.read(f), "typescript"));
return ctx.compress.auto(skeletons.join("\n---\n"));SDK API:
// File operations
ctx.files.read(path) // Read file content
ctx.files.glob(pattern) // Find files by pattern
ctx.files.exists(path) // Check if file exists
// Code analysis
ctx.code.parse(content, lang) // Parse to structure
ctx.code.extract(content, lang, {type, name}) // Extract element
ctx.code.skeleton(content, lang) // Signatures only
// Compression
ctx.compress.auto(content, hint?) // Auto-detect and compress
ctx.compress.logs(logs) // Log summarization
ctx.compress.diff(diff) // Diff compression
ctx.compress.semantic(content, ratio?) // TF-IDF compression
// Git
ctx.git.diff(ref?) // Get diff
ctx.git.log(limit?) // Commit history
ctx.git.blame(file, line?) // Blame info
ctx.git.status() // Working tree status
ctx.git.branch() // Current branch info
// Search
ctx.search.grep(pattern, glob?) // Search file contents
ctx.search.symbols(query, glob?) // Find code symbols
ctx.search.files(pattern) // Find files by pattern
ctx.search.references(symbol, glob?) // Find symbol references
// Analysis
ctx.analyze.dependencies(file) // File dependencies
ctx.analyze.callGraph(fn, file, depth?) // Call graph
ctx.analyze.exports(file) // Exported symbols
ctx.analyze.structure(dir, depth?) // Directory structure
// Pipeline
ctx.pipeline(steps) // Run step array
ctx.pipeline.codebaseOverview(dir?) // Quick overview
ctx.pipeline.findUsages(symbol) // Find all usages
ctx.pipeline.analyzeDeps(file) // Dependency analysis
// Utilities
ctx.utils.countTokens(text) // Count tokens
ctx.utils.detectType(content) // Detect content type
ctx.utils.detectLanguage(path) // Detect language from pathDistill's 3 tools add minimal overhead to every API call:
| Tool Schemas | Description | |
|---|---|---|
| Distill | ~2,000 tokens | 3 always-loaded tools |
| Equivalent | ~10,000+ tokens | 20+ individual tools doing the same |
All 3 tools use _meta['anthropic/alwaysLoad'] — present from turn 1 with zero discovery friction.
distill-mcp setup # Auto-configure detected IDEs
distill-mcp setup --claude # Configure Claude Code only
distill-mcp setup --cursor # Configure Cursor only
distill-mcp doctor # Verify installation
distill-mcp serve # Start MCP server
distill-mcp analyze # Analyze codebase token usage
distill-mcp --help # Show helpAfter running distill-mcp setup, your config will include:
{
"mcpServers": {
"distill": {
"command": "npx",
"args": ["distill-mcp", "serve"]
}
}
}Configuration is automatically added to the appropriate settings file.
Code execution runs in a sandboxed environment with 7 security layers:
- Static analysis blocks
eval,require,import(),process,Reflect,Proxy - File access restricted to working directory
- Sensitive files blocked (
.env, credentials, keys) - Git commands allowlisted (no push, fetch, clone)
- Memory limit: 128MB | Timeout: 30s | Output cap: 4000 tokens
bun install # Install dependencies
bun run build # Build all packages
bun run test # Run tests
bun run dev # Start dev server
bun run check-types # TypeScript type check
bun run lint # ESLint- GitHub Discussions — Questions, ideas, feedback
- Issues — Bug reports
Contributions welcome! See CONTRIBUTING.md for guidelines.
Priority areas:
- New language parsers (Java, C#, Kotlin)
- SDK extensions
- Documentation
MIT
npm · GitHub · Documentation · Discussions