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

Add patterns — New conversion patterns go in skills/mcp-codegen/references/
Keep it lean — SKILL.md stays under 500 lines. Detailed docs go in references/
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

MCP Servers