mcp2cli

MCP servers are expensive. CLIs are not.

A Claude Code plugin that converts MCP servers into token-efficient CLI tools.

---

Why?

MCP servers load every tool schema into the agent's context window on startup. For a server with 30 tools, that's ~55,000 tokens burned before the agent does anything.

A CLI tool with a SKILL.md loads on-demand — only when relevant — and returns compact text instead of verbose JSON.

	MCP	CLI + Skill
Startup	Load all tool schemas into context	Nothing loaded
Token cost	~55,000 tokens for 30 tools	0 tokens until first use
On use	JSON + metadata per call	Load SKILL.md once (~2K tokens)
Output	Verbose structured JSON	Compact plain text

Bottom line: 94–96% token savings across all scales.

	MCP	CLI + Skill	Savings
5 tools	8,000 tok	500 tok	94%
30 tools	55,000 tok	2,000 tok	96%
100 tools	134,000 tok	5,000 tok	96%

The canonical example: Playwright shipped a CLI + SKILL.md alongside their MCP server — specifically for coding agents where token efficiency matters.

---

Quick Start

1. Clone the plugin:

git clone https://github.com/myeolinmalchi/mcp2cli.git

2. Load it in Claude Code:

claude --plugin-dir ./mcp2cli

3. Convert your first MCP server:

/convert ./my-mcp-server

That's it. The plugin analyzes the server, generates CLI code, and creates a SKILL.md — all in one step.

---

How It Works

The plugin runs a 5-phase conversion pipeline:

Phase	Name	What happens	Output
1	Analyze	Read MCP source, extract tools, params, outputs, auth	Structured analysis table
2	Design	Map tool names → CLI commands, params → flags	Command structure spec
3	Generate	Write TypeScript CLI reusing MCP's business logic	Working npm CLI tool
4	Skill	Generate SKILL.md under 500 lines with examples	SKILL.md file
5	Validate	Run each command, compare with MCP output	Test report

Supported MCP Patterns

The plugin classifies MCP servers into 4 tiers by CLI conversion feasibility:

Tier	Patterns	CLI Fit
1	Local System Tool, SaaS API Wrapper, DevOps, Document/Media Processing	Excellent
2	Database, Search, Proxy, Multi-tool, Messaging, Monitoring	Good
3	Browser Automation, Code Execution, Memory, Auth/Identity	Partial
4	Aggregator/Gateway, Reasoning/Cognitive	Not recommended

---

Commands

Command	Description
/convert <path>	Full end-to-end conversion (all 5 phases)
/analyze-mcp <path>	Analysis only — assess feasibility, no code gen
/generate-skill <cli-name>	Generate SKILL.md for an existing CLI tool

/convert ./my-mcp-server
/convert https://github.com/user/their-mcp-server
/analyze-mcp ./my-mcp-server
/generate-skill my-existing-cli

---

What's Inside

mcp2cli/
├── .claude-plugin/
│   └── plugin.json
│
├── skills/
│   ├── mcp-analyze/                    # MCP server analysis & pattern classification
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── pattern-classification.md
│   │
│   ├── mcp-codegen/                    # TypeScript CLI code generation
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── cli-scaffold.md
│   │       ├── porting-cheatsheet.md
│   │       ├── tier-1-templates.md
│   │       ├── tier-2-templates.md
│   │       └── tier-3-strategies.md
│   │
│   └── skill-author/                   # SKILL.md generation
│       ├── SKILL.md
│       └── references/
│           └── skill-template.md
│
├── commands/
│   ├── convert.md                      # /convert — orchestrates all skills
│   ├── analyze-mcp.md                  # /analyze-mcp — analysis only
│   └── generate-skill.md              # /generate-skill — SKILL.md for existing CLI
│
└── agents/
    └── mcp-analyzer.md                 # Subagent for MCP source analysis

Component	Count	Purpose
Skills	3	mcp-analyze, mcp-codegen, skill-author
Commands	3	/convert (orchestrator), /analyze-mcp, /generate-skill
Agents	1	MCP server source code analysis

---

When to Convert (and When Not To)

Convert to CLI	Keep as MCP
Stateless request/response tools	Real-time streaming / subscriptions
Text or JSON output	Binary streams (audio, video)
Infrequently used tools (schema overhead > value)	Bidirectional communication
Simpler deployment desired	Complex state management across calls

Rule of thumb: If the MCP tool is basically input → API call → output, it should be a CLI.

---

Contributing

1. Add patterns — New conversion patterns go in skills/mcp-codegen/references/
2. Keep it lean — SKILL.md stays under 500 lines. Detailed docs go in references/
3. Test conversions — Point /convert at any MCP server and verify the output works

# Test locally
claude --plugin-dir ./mcp2cli

---

References

• Playwright CLI + SKILL.md — The canonical MCP-to-CLI migration
• mcp-cli — Dynamic tool discovery bridge (99% token reduction)
• MCP vs CLI Benchmarks — 33% token efficiency advantage for CLI
• Cloudflare Code Mode — 99.9% token reduction via single-tool MCP
• Claude Code Skills Docs — Official skill authoring guide
• Claude Code Plugins Docs — Official plugin development guide