mcp-crush

One line: npx mcp-crush wrap -- <your-mcp-cmd> (or bunx mcp-crush wrap -- <your-mcp-cmd>): stdio proxy that shrinks MCP tool catalogs and prunes oversized JSON responses by 60-85%.

Why

Large MCP servers (GitHub, Cloudflare, Notion) dump thousands of tokens into tools/list before your agent does any work. Local 8k models cannot fit them, and cloud APIs bill you for that handshake on every session.

mcp-crush sits in the middle using the same JSON-RPC wire protocol while emitting smaller payloads.

Install

Bun / npm:

bunx mcp-crush audit
npx mcp-crush audit

# or install in your project / globally
bun add -d mcp-crush
npm i -D mcp-crush

JSR:

bunx jsr add @kanchingyg/mcp-crush
npx jsr add @kanchingyg/mcp-crush

Quick start

# Inspect token overhead from your MCP config
npx mcp-crush audit
bunx mcp-crush audit

# Wrap any stdio MCP server
npx mcp-crush wrap -- npx -y @modelcontextprotocol/server-github

# Ollama-friendly schema pack (~600 token budget)
npx mcp-crush wrap --ollama-pack -- npx -y @modelcontextprotocol/server-github

# Expose audit/compress/prune as MCP tools
npx mcp-crush --mcp

Ollama / LM Studio

Set OLLAMA_HOST (default http://127.0.0.1:11434). With --mcp, mcp-crush probes n_ctx and tunes truncation automatically. Use --ollama-pack on wrap to cap tools/list schemas around 600 tokens.

MCP Tools Reference

Editor and Agent Integration

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "mcp-crush": {
      "command": "npx",
      "args": ["-y", "mcp-crush", "--mcp"]
    }
  }
}

Claude Code CLI

claude mcp add mcp-crush -- npx -y mcp-crush --mcp

Programmatic Usage (JSR / TypeScript)

import * as bridge from "jsr:@kanchingyg/mcp-crush/bridge";

Runtime Safety and Guardrails

• Stdio frame isolation: --mcp redirects stray console.log to stderr so JSON-RPC on stdout stays valid.
• Read-only default: Mutating tools need --allow-write; --dry-run blocks writes.
• Loop breaker: Identical tool calls halt after three repeats (SHA-256 of name + args).
• Context budget: wrap / MCP probe n_ctx and head/tail-truncate large tool output.
• Config path sandbox: audit_mcp_config resolves configPath under the process cwd.
• Secret redaction: AWS keys, bearer tokens, and sk-* patterns scrubbed from tool text.

License

MIT