Claude Code Integration

This guide walks you through setting up Distill with Claude Code.

Prerequisites

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

Quick Setup (30 seconds)

npm install -g distill-mcp
distill-mcp setup

Done! Restart Claude Code and you're ready.

Manual Setup

If the automatic setup didn't work:

Option 1: Via CLI (recommended)

claude mcp add distill -- npx distill-mcp serve

Option 2: Via 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

Check that the server is properly configured:

claude mcp list

Or in Claude Code, use the /mcp command to see connected servers.

Then ask Claude to read a source file with smart_file_read to verify that Distill tools are available.

Using Distill Tools

Smart File Reading

Instead of reading entire files, use smart_file_read:

Use smart_file_read to get the structure of src/server.ts

Compressing Build Output

When you get build errors:

Use auto_optimize to compress this build output: [paste output]

Recommended CLAUDE.md Setup

Add this to your project's CLAUDE.md to enforce Distill usage:

## MCP Tool Usage

When reading source code files for exploration, use:
- `smart_file_read` instead of `Read` for .ts/.js/.py files

When you see large command output (>500 chars):
- Use `auto_optimize` to compress it

Installing Project Hooks

Distill can install hooks that remind you to use optimization tools:

distill-mcp setup --hooks

This adds hooks to your project that:

• Suggest smart_file_read when reading code files
• Suggest auto_optimize for large bash outputs
• Remind about MCP tools on each prompt

Troubleshooting

MCP Server Not Starting

1. Check Node.js version: node --version (needs 20+)
2. Run doctor: distill-mcp doctor
3. Check logs in Claude Code's output panel

Tools Not Appearing

1. Check configuration: claude mcp list
2. Verify JSON syntax is valid in ~/.claude.json
3. Try running npx distill-mcp serve manually to check for errors
4. Use /mcp in Claude Code to see server status

Permission Issues

On macOS/Linux, you may need to make the command executable:

chmod +x $(which distill-mcp)