mcp2cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mcp2cli

Turn any MCP server or OpenAPI spec into a CLI at runtime. No codegen.

可在运行时将任意MCP服务器或OpenAPI规范转换为CLI工具，无需代码生成。

Install

安装

bash

undefined

bash

undefined

Run directly (no install needed)

直接运行（无需安装）

uvx mcp2cli --help

Or install

或进行安装

pip install mcp2cli

undefined

pip install mcp2cli

undefined

Core Workflow

核心工作流程

Connect to a source (MCP server or OpenAPI spec)
Discover available commands with
```
--list
```
Inspect a specific command with
```
<command> --help
```
Execute the command with flags

bash

undefined

连接到数据源（MCP服务器或OpenAPI规范）
使用
```
--list
```
发现可用命令
使用
```
<command> --help
```
查看特定命令的详细信息
通过参数执行命令

bash

undefined

MCP over HTTP

基于HTTP的MCP

mcp2cli --mcp https://mcp.example.com/sse --list mcp2cli --mcp https://mcp.example.com/sse create-task --help mcp2cli --mcp https://mcp.example.com/sse create-task --title "Fix bug"

mcp2cli --mcp https://mcp.example.com/sse --list mcp2cli --mcp https://mcp.example.com/sse create-task --help mcp2cli --mcp https://mcp.example.com/sse create-task --title "修复Bug"

MCP over stdio

基于标准输入输出的MCP

mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" --list mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" read-file --path /tmp/hello.txt

OpenAPI spec (remote or local, JSON or YAML)

OpenAPI规范（远程或本地，JSON或YAML格式）

mcp2cli --spec https://petstore3.swagger.io/api/v3/openapi.json --list mcp2cli --spec ./openapi.json --base-url https://api.example.com list-pets --status available

undefined

mcp2cli --spec https://petstore3.swagger.io/api/v3/openapi.json --list mcp2cli --spec ./openapi.json --base-url https://api.example.com list-pets --status available

undefined

CLI Reference

CLI参考

mcp2cli [global options] <subcommand> [command options]

Source (mutually exclusive, one required):
  --spec URL|FILE       OpenAPI spec (JSON or YAML, local or remote)
  --mcp URL             MCP server URL (HTTP/SSE)
  --mcp-stdio CMD       MCP server command (stdio transport)

Options:
  --auth-header K:V     HTTP header sent with requests (repeatable)
  --base-url URL        Override base URL from spec
  --env KEY=VALUE       Env var for stdio server process (repeatable)
  --cache-key KEY       Custom cache key
  --cache-ttl SECONDS   Cache TTL (default: 3600)
  --refresh             Bypass cache
  --list                List available subcommands
  --pretty              Pretty-print JSON output
  --raw                 Print raw response body
  --toon                Encode output as TOON (token-efficient for LLMs)
  --version             Show version

Subcommands and flags are generated dynamically from the source.

mcp2cli [全局选项] <子命令> [命令选项]

数据源（互斥，必须指定其一）：
  --spec URL|FILE       OpenAPI规范（JSON或YAML格式，本地或远程）
  --mcp URL             MCP服务器地址（HTTP/SSE协议）
  --mcp-stdio CMD       MCP服务器命令（标准输入输出传输）

选项：
  --auth-header K:V     请求时携带的HTTP请求头（可重复添加）
  --base-url URL        覆盖规范中的基础地址
  --env KEY=VALUE       传递给标准输入输出服务器进程的环境变量（可重复添加）
  --cache-key KEY       自定义缓存键
  --cache-ttl SECONDS   缓存过期时间（默认：3600秒）
  --refresh             绕过缓存，强制刷新
  --list                列出所有可用子命令
  --pretty              格式化输出JSON内容
  --raw                 输出原始响应体
  --toon                将输出编码为TOON格式（大语言模型的高效令牌格式）
  --version             显示版本信息

子命令和参数会根据数据源动态生成。

Patterns

使用模式

Authentication

身份验证

bash

undefined

bash

undefined

API key header

API密钥请求头

mcp2cli --spec ./spec.json --auth-header "Authorization:Bearer tok_..." list-items

Multiple headers

多个请求头

mcp2cli --mcp https://mcp.example.com/sse
--auth-header "x-api-key:sk-..."
--auth-header "x-org-id:org_123"
search --query "test"

undefined

mcp2cli --mcp https://mcp.example.com/sse
--auth-header "x-api-key:sk-..."
--auth-header "x-org-id:org_123"
search --query "测试"

undefined

POST with JSON body from stdin

通过标准输入传递JSON体的POST请求

bash

echo '{"name": "Fido", "tag": "dog"}' | mcp2cli --spec ./spec.json create-pet --stdin

bash

echo '{"name": "Fido", "tag": "dog"}' | mcp2cli --spec ./spec.json create-pet --stdin

Env vars for stdio servers

标准输入输出服务器的环境变量

bash

mcp2cli --mcp-stdio "node server.js" --env API_KEY=sk-... --env DEBUG=1 search --query "test"

bash

mcp2cli --mcp-stdio "node server.js" --env API_KEY=sk-... --env DEBUG=1 search --query "测试"

Caching

缓存

Specs and MCP tool lists are cached in

~/.cache/mcp2cli/

(1h TTL). Local files are never cached.

bash

mcp2cli --spec https://api.example.com/spec.json --refresh --list    # Force refresh
mcp2cli --spec https://api.example.com/spec.json --cache-ttl 86400 --list  # 24h TTL

规范和MCP工具列表会缓存到

~/.cache/mcp2cli/

目录（默认1小时过期）。本地文件不会被缓存。

bash

mcp2cli --spec https://api.example.com/spec.json --refresh --list    # 强制刷新缓存
mcp2cli --spec https://api.example.com/spec.json --cache-ttl 86400 --list  # 设置24小时缓存过期时间

TOON output (token-efficient for LLMs)

TOON输出（适合大语言模型的高效令牌格式）

bash

mcp2cli --mcp https://mcp.example.com/sse --toon list-tags

Best for large uniform arrays — 40-60% fewer tokens than JSON.

bash

mcp2cli --mcp https://mcp.example.com/sse --toon list-tags

非常适合大型统一数组——相比JSON格式可减少40-60%的令牌数量。

Generating a Skill from an API

基于API生成技能

When the user asks to create a skill from an MCP server or OpenAPI spec, follow this workflow:

Discover all available commands:

bash

uvx mcp2cli --mcp https://target.example.com/sse --list

Inspect each command to understand parameters:

bash

uvx mcp2cli --mcp https://target.example.com/sse <command> --help

Test key commands to verify they work:

bash

uvx mcp2cli --mcp https://target.example.com/sse <command> --param value

Create a SKILL.md that teaches another AI agent how to use this API via mcp2cli. Include:
- The source flag (
```
--mcp
```
  ,
```
--mcp-stdio
```
  , or
```
--spec
```
  ) and URL
- Any required auth headers
- Common workflows with example commands
- The
```
--list
```
  and
```
--help
```
  discovery pattern for commands not covered

The generated skill should use mcp2cli as its execution layer — the agent runs

uvx mcp2cli ...

commands rather than making raw HTTP/MCP calls.

当用户要求基于MCP服务器或OpenAPI规范创建技能时，请遵循以下流程：

发现所有可用命令：

bash

uvx mcp2cli --mcp https://target.example.com/sse --list

查看每个命令的参数详情：

bash

uvx mcp2cli --mcp https://target.example.com/sse <command> --help

测试关键命令以验证可用性：

bash

uvx mcp2cli --mcp https://target.example.com/sse <command> --param value

创建SKILL.md文档，指导其他AI Agent如何通过mcp2cli使用该API。文档需包含：
- 数据源标识（
```
--mcp
```
  、
```
--mcp-stdio
```
  或
```
--spec
```
  ）及地址
- 所有必需的身份验证请求头
- 常见工作流及示例命令
- 针对未覆盖命令的
```
--list
```
  和
```
--help
```
  发现模式

生成的技能应将mcp2cli作为执行层——Agent需运行

uvx mcp2cli ...

命令，而非直接发起原始HTTP/MCP请求。