Mcptoon

Zero-Config Token Optimization & Unified Governance for MCP Tools and Agent Skills

Install 1,000 skills and 1,000 MCP tools locally — and never worry about context flooding. Cuts tool context by ~90% (99.2% on 255 tools) with zero config across 103+ desktop and CLI agents.

🌐 Official Website · 🧮 30s Token Tax Calculator · 🇨🇳 中文文档 · 📖 Developer Docs

https://github.com/user-attachments/assets/0272d3a8-c74f-428d-8559-fbf804ce0685

⚡ Core Capabilities at a Glance

💰 Token & Context Optimization	🛠️ Universal Tool Management
• ✅ Compact Name Index (-99.2%): 72k tokens → 581 tokens name-only index• ✅ Lossless Compression (CCR): Reversible with handle retrieval (retrieve)• ✅ Session Deduplication: Blocks byte-identical output duplication in turn• ✅ Honest Measurements: Real tiktoken accounting via mcptoon bench	• ✅ 17,000+ Registry Discovery: Natural language search (search)• ✅ Uniform CLI Execution (call): Headless driver for any MCP tool• ✅ On-Demand Inspection (inspect): Schema pulled only when needed• ✅ Diagnostic Doctor (doctor): Self-heals stdio pipes & environments

🧠 Skills Governance	📚 Zero-Tax Docs Routing (mcptoon docs)
• ✅ Single-Source Multi-Agent Sync: Claude, Cursor, Roo, OpenCode• ✅ Self-Installed Skill Included: Bundles /mcptoon official agent skill• ✅ Offline BM25 Skill Router: <5ms matching, zero model API costs• ✅ Version Gate (--version-gate): Blocks unversioned content drift• ✅ Tombstone Removal: Prevents dead skills from reviving via git pull	• ✅ Markdown Tree Indexing: Automatic index over large doc directories• ✅ Targeted Chapter Feeding: Feeds 1 chapter instead of 19 chapters• ✅ Zero Model Overhead: Pure offline BM25 keyword matching engine• ✅ Context Tax Shield: Drops 40k doc tokens to 17k per lookup

🔌 103+ AI Clients Supported	🛡️ Engineering Discipline
• ✅ 103+ Clients Out-of-the-Box: Claude Code, Cursor, Windsurf, Zed, Cline...• ✅ Dual Modes (CLI & Native MCP): 42 CLI direct + 61 MCP serve fallback• ✅ Transparent Session Footer: Live savings breakdown printed after turns	• ✅ Zero Dependencies: 100% Python standard library (pyproject.toml clean)• ✅ Ultra Lightweight: Only 363KB total package footprint, installs in 2s• ✅ 100% Local & Private: No cloud calls, zero telemetry, air-gap ready• ✅ Strict XDG Compliant: Sandbox-friendly config isolation via --dir

---

🚀 Quick Start (Choose Your Way)

🤖 Modern Way: Just Talk to Your Agent (Zero Memorization)

When installed, mcptoon automatically injects its own official skill (/mcptoon) into your agents. You never need to memorize terminal commands — just ask directly in Cursor, Claude Code, Windsurf, or DSH:

# Ask the built-in skill anytime:
"Load /mcptoon skill and check what MCP tools I currently have."
"Help me find an MCP tool that converts HTML to PDF and call it."
"The tool output was truncated, retrieve the full original copy."
"How many tokens did mcptoon save for me today?"
"Doctor self-check: are all my MCP servers connected properly?"

Your agent loads /mcptoon and drives everything behind the scenes!

⚡ Terminal Way: 30-Second Setup