Distill - MCP Server for LLM token optimization and context compression
npm install distill-mcp> Extract the essence. Compress the context. Save tokens.
Distill is an open-source MCP server that optimizes LLM token usage through intelligent context compression. Works with Claude Code, Cursor, and Windsurf.


| Problem | Distill Solution | Savings |
|---------|------------------|---------|
| Large build outputs | Auto-compress errors | 80-95% |
| Reading entire files | AST-based extraction | 50-70% |
| Multiple tool calls | TypeScript SDK execution | 98% |
| Verbose logs | Smart summarization | 80-90% |
``bashRun directly with npx
npx distill-mcp
$3
`bash
claude mcp add distill -- npx distill-mcp
`Features
- Smart File Reading - Extract functions, classes, or signatures without loading entire files
- Auto Compression - Detects content type and applies optimal compression
- Code Execution SDK - Write TypeScript instead of chaining tool calls
- Lazy Loading - Only loads tools when needed (85% token overhead reduction)
- 7 Languages - TypeScript, JavaScript, Python, Go, Rust, PHP, Swift
MCP Tools
$3
| Tool | Purpose | Savings |
|------|---------|---------|
|
auto_optimize | Auto-detect and compress content | 40-95% |
| smart_file_read | Read code with AST extraction | 50-70% |
| code_execute | Execute TypeScript with SDK | 98% |
| discover_tools | Browse/load additional tools | - |$3
| Tool | Purpose | Savings |
|------|---------|---------|
|
semantic_compress | TF-IDF based compression | 40-60% |
| summarize_logs | Summarize server/test/build logs | 80-90% |
| analyze_build_output | Parse build errors | 95%+ |
| deduplicate_errors | Group repeated errors | 80-95% |
| diff_compress | Compress git diffs | 50-80% |
| context_budget | Pre-flight token estimation | - |
| session_stats | Usage analytics | - |Usage Examples
$3
`bash
Get file structure overview
mcp__distill__smart_file_read filePath="src/server.ts"Extract specific function
mcp__distill__smart_file_read filePath="src/server.ts" target={"type":"function","name":"createServer"}Get skeleton (signatures only)
mcp__distill__smart_file_read filePath="src/server.ts" skeleton=true
`$3
`bash
After a failed build, compress the output
mcp__distill__auto_optimize content=""
`$3
The
code_execute tool provides 98% token savings by letting LLMs write TypeScript:`bash
mcp__distill__code_execute code="return ctx.compress.auto(ctx.files.read('logs.txt'))"
`SDK API:
`typescript
// File operations
ctx.files.read(path)
ctx.files.glob(pattern)
ctx.files.exists(path)// Code analysis
ctx.code.skeleton(content, lang)
ctx.code.extract(content, lang, {type, name})
ctx.code.parse(content, lang)
// Compression
ctx.compress.auto(content, hint?)
ctx.compress.logs(logs)
ctx.compress.diff(diff)
ctx.compress.semantic(content, ratio?)
// Git operations
ctx.git.diff(ref?)
ctx.git.log(limit?)
ctx.git.blame(file, line?)
// Search
ctx.search.grep(pattern, glob?)
ctx.search.symbols(query)
// Analysis
ctx.analyze.dependencies(file)
ctx.analyze.callGraph(fn)
`$3
`bash
Browse available tools (metadata only)
mcp__distill__discover_tools category="compress"Load tools when needed
mcp__distill__discover_tools category="compress" load=trueTOON format for compact output
mcp__distill__discover_tools format="toon"
`CLI Commands
`bash
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 help
`IDE Configuration
$3
After running
distill-mcp setup, your config will include:`json
{
"mcpServers": {
"distill": {
"command": "npx",
"args": ["distill-mcp", "serve"]
}
}
}
`$3
Configuration is automatically added to the appropriate settings file.
Token Overhead
Distill uses lazy loading to minimize overhead:
| Mode | Tokens | Description |
|------|--------|-------------|
| Core only | 264 | Default (4 tools) |
| All tools | 1,108 | Full suite (21 tools) |
| Savings | 76% | Lazy vs eager loading |
Security
Code execution runs in a sandboxed environment:
- Blocked:
eval, require, import(), process, global
- File access restricted to working directory
- Sensitive files blocked (.env, credentials, keys)
- Memory limit: 128MB, Timeout: 30sDevelopment
`bash
Install dependencies
bun installRun tests
bun run testBuild
bun run buildStart dev server
bun run dev
``Contributions welcome! See CONTRIBUTING.md for guidelines.
Priority areas:
- New language parsers (Java, C#, Kotlin)
- SDK extensions
- Documentation
MIT
---
npm · GitHub · Documentation