Installation

Get started with Distill in under a minute.

Quick start

npm install -g distill-mcp
distill-mcp setup

The setup command detects Claude Code and registers it as the MCP client. That's it.

Prerequisites

Node.js 20+
Claude Code installed (npm install -g @anthropic-ai/claude-code or download)

Without a global install

If you prefer to skip the global install, use npx:

npx distill-mcp serve

Then add the MCP entry to your Claude Code configuration (see next section).

Manual Claude Code configuration

If distill-mcp setup didn't work, or if you prefer to edit the file by hand.

Via the Claude Code CLI

claude mcp add distill -- npx distill-mcp serve

Via the configuration file

Edit ~/.claude.json (global) or .mcp.json (per-project):

{
  "mcpServers": {
    "distill": {
      "command": "distill-mcp",
      "args": ["serve"]
    }
  }
}

Or with npx (no global install):

{
  "mcpServers": {
    "distill": {
      "command": "npx",
      "args": ["distill-mcp", "serve"]
    }
  }
}

Verify installation

distill-mcp doctor

Then restart Claude Code and ask: "Use auto_optimize to compress this build output".

CLI Reference

Binary: distill-mcp. Four commands.

distill-mcp serve      # Start the MCP server on stdio transport
distill-mcp setup      # Configure Claude Code and install hooks/agents
distill-mcp doctor     # Diagnose installation
distill-mcp analyze    # Analyze token usage in a codebase
distill-mcp --help     # Show all options
distill-mcp --version  # Print installed version

`distill-mcp serve`

Flag	Effect
`--verbose`	Enable verbose logging on stderr (stdout stays the MCP channel)

`distill-mcp setup`

With no flag, setup configures Claude Code by default and installs what is needed. The flags below enable opt-in extensions introduced in v0.10.0:

Flag	Effect
`--hooks`	Install the pre-commit hook in the current project
`--install-precompact-hook`	Add the PreCompact hook into `~/.claude/settings.json` (idempotent, atomic via tempfile + rename)
`--uninstall-precompact-hook`	Cleanly remove the PreCompact entry
`--install-agent`	Copy the `distill-compressor.md` template into `~/.claude/agents/`
`--uninstall-agent`	Remove the installed agent

Cross-cutting options:

Flag	Effect
`--dry-run`	Print the changes without mutating the filesystem
`--user-dir=<path>`	Override `HOME` for locating `settings.json` (useful in tests)
`--force`, `-f`	Overwrite an existing configuration even if it differs from the template

`distill-mcp doctor`

No flags. Checks Node version, distill-mcp availability, detected Claude Code configuration, and the state of installed hooks.

`distill-mcp analyze`

Flag	Effect
`--patterns`, `-p`	Glob patterns to scan (default `*/.{ts,tsx,js,jsx,py,go,rs}`)
`--threshold`, `-t`	Token warning threshold (default `2000`)
`--json`, `-j`	Emit JSON instead of the text report
`--output`, `-o`	Write the report to a file instead of stdout

Next steps

MCP Tools Reference — The 3 tools: auto_optimize, smart_file_read, code_execute
Claude Code Guide — Full integration guide
Troubleshooting — Common issues and solutions

Installation

On this page