mcp2cli
Convert MCP servers to token-efficient CLI tools with auto-generated SKILL.md files for Claude Code agents
Open source Open in the app JSON README (API)
About
Convert MCP servers to token-efficient CLI tools with auto-generated SKILL.md files for Claude Code agents
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- myeolinmalchi
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 4
- Forks
- 2
- Last push
- 2026-03-07T03:43:21Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
myeolinmalchi/mcp2cli/mcp2cli
README
# 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:**
```bash
git clone https://github.com/myeolinmalchi/mcp2cli.git
```
**2. Load it in Claude Code:**
```bash
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 |
```bash
/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
```bash
# Test locally
claude --plugin-dir ./mcp2cli
```
---
## References
- [Playwright CLI + SKILL.md](https://www.npmjs.com/package/@playwright/cli) — The canonical MCP-to-CLI migration
- [mcp-cli](https://www.philschmid.de/mcp-cli) — Dynamic tool discovery bridge (99% token reduction)
- [MCP vs CLI Benchmarks](https://mariozechner.at/posts/2025-08-15-mcp-vs-cli/) — 33% token efficiency advantage for CLI
- [Cloudflare Code Mode](https://blog.cloudflare.com/code-mode-mcp/) — 99.9% token reduction via single-tool MCP
- [Claude Code Skills Docs](https://code.claude.com/docs/en/skills) — Official skill authoring guide
- [Claude Code Plugins Docs](https://code.claude.com/docs/en/plugins) — Official plugin development guide