Mcp2cli：Token 效率提升 96-99% 的 MCP 工具

将任何 MCP 服务器、OpenAPI 规范或 GraphQL 端点转换为 CLI —— 在运行时进行，无需任何代码生成。每轮节省 96–99% 的工具架构浪费的 token。阅读完整文章

# Run directly without installing
uvx mcp2cli --help

# Or install globally
uv tool install mcp2cli

mcp2cli 附带一个可安装的技能，可教会 AI 编码 agent（Claude Code、Cursor、Codex）如何使用它。安装后，你的 agent 可以发现并调用任何 MCP 服务器或 OpenAPI 端点 —— 甚至可以从 API 生成新的技能。

npx skills add knowsuchagency/mcp2cli --skill mcp2cli

安装后，尝试以下这样的 prompt：

mcp2cli --mcp https://mcp.example.com/sse — 与 MCP 服务器交互

mcp2cli create a skill for https://api.example.com/openapi.json — 从 API 生成技能

MCP over HTTP

# Connect to an MCP server over HTTP
mcp2cli --mcp https://mcp.example.com/sse --list

# Call a tool
mcp2cli --mcp https://mcp.example.com/sse search --query "test"

# With auth header
mcp2cli --mcp https://mcp.example.com/sse --auth-header "x-api-key:sk-..." \
  query --sql "SELECT 1"

# Force a specific transport (skip streamable HTTP fallback dance)
mcp2cli --mcp https://mcp.example.com/sse --transport sse --list

# Search tools by name or description (case-insensitive substring match)
mcp2cli --mcp https://mcp.example.com/sse --search "task"

--search 暗含 --list，并在所有模式中工作（--mcp、--spec、--graphql、--mcp-stdio）。

OAuth 支持

支持需要 OAuth 的 API —— 跨越 MCP、OpenAPI 和 GraphQL 模式。mcp2cli 自动处理 token 获取、缓存和刷新。

# Authorization code + PKCE flow (opens browser for login)
mcp2cli --mcp https://mcp.example.com/sse --oauth --list
mcp2cli --spec https://api.example.com/openapi.json --oauth --list
mcp2cli --graphql https://api.example.com/graphql --oauth --list

# Client credentials flow (machine-to-machine, no browser)
mcp2cli --spec https://api.example.com/openapi.json \
  --oauth-client-id "my-client-id" \
  --oauth-client-secret "my-secret" \
  list-pets

# With specific scopes
mcp2cli --graphql https://api.example.com/graphql --oauth --oauth-scope "read write" users

# Local spec file — use --base-url for OAuth discovery
mcp2cli --spec ./openapi.json --base-url https://api.example.com --oauth --list

Token 被持久化在 ~/.cache/mcp2cli/oauth/ 中，因此后续调用会重用现有 token，并在过期时自动刷新。

从环境变量或文件读取密钥

敏感值（--auth-header 值、--oauth-client-id、--oauth-client-secret）支持 env: 和 file: 前缀，以避免将密钥作为 CLI 参数传递（这在进程列表中是可见的）：

# Read from environment variable
mcp2cli --mcp https://mcp.example.com/sse \
  --auth-header "Authorization:env:MY_API_TOKEN" \
  --list

# Read from file
mcp2cli --mcp https://mcp.example.com/sse \
  --oauth-client-secret "file:/run/secrets/client_secret" \
  --oauth-client-id "my-client-id" \
  --list

# Works with secret managers that inject env vars
fnox exec -- mcp2cli --mcp https://mcp.example.com/sse \
  --oauth-client-id "env:OAUTH_CLIENT_ID" \
  --oauth-client-secret "env:OAUTH_CLIENT_SECRET" \
  --list

MCP stdio

# List tools from an MCP server
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" --list

# Call a tool
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
  read-file --path /tmp/hello.txt

# Pass environment variables to the server process
mcp2cli --mcp-stdio "node server.js" --env API_KEY=sk-... --env DEBUG=1 \
  search --query "test"

OpenAPI 模式

# List all commands from a remote spec
mcp2cli --spec https://petstore3.swagger.io/api/v3/openapi.json --list

# Call an endpoint
mcp2cli --spec ./openapi.json --base-url https://api.example.com list-pets --status available

# With auth
mcp2cli --spec ./spec.json --auth-header "Authorization:Bearer tok_..." create-item --name "Test"

# POST with JSON body from stdin
echo '{"name": "Fido", "tag": "dog"}' | mcp2cli --spec ./spec.json create-pet --stdin

# Local YAML spec
mcp2cli --spec ./api.yaml --base-url http://localhost:8000 --list

GraphQL 模式

# List all queries and mutations from a GraphQL endpoint
mcp2cli --graphql https://api.example.com/graphql --list

# Call a query
mcp2cli --graphql https://api.example.com/graphql users --limit 10

# Call a mutation
mcp2cli --graphql https://api.example.com/graphql create-user --name "Alice" --email "alice@example.com"

# Override auto-generated selection set fields
mcp2cli --graphql https://api.example.com/graphql users --fields "id name email"

# With auth
mcp2cli --graphql https://api.example.com/graphql --auth-header "Authorization:Bearer tok_..." users

mcp2cli 自动对端点进行内省，发现查询和变更，自动生成选择集，并构建带有适当变量声明的参数化查询。无 SDL 解析，无代码生成 —— 只需指向并运行。

Bake mode —— 保存连接设置

厌倦了在每次调用时重复 --spec/--mcp/--mcp-stdio 加认证标志？将它们烤入一个命名配置中：

# Create a baked tool from an OpenAPI spec
mcp2cli bake create petstore --spec https://api.example.com/spec.json \
  --exclude "delete-*,update-*" --methods GET,POST --cache-ttl 7200

# Create a baked tool from an MCP stdio server
mcp2cli bake create mygit --mcp-stdio "npx @mcp/github" \
  --include "search-*,list-*" --exclude "delete-*"

# Use a baked tool with @ prefix — no connection flags needed
mcp2cli @petstore --list
mcp2cli @petstore list-pets --limit 10
mcp2cli @mygit search-repos --query "rust"

# Manage baked tools
mcp2cli bake list                         # show all baked tools
mcp2cli bake show petstore                # show config (secrets masked)
mcp2cli bake update petstore --cache-ttl 3600
mcp2cli bake remove petstore
mcp2cli bake install petstore             # creates ~/.local/bin/petstore wrapper
mcp2cli bake install petstore --dir ./scripts/  # install wrapper to custom directory

--include — 逗号分隔的 glob 模式以白名单工具（例如 "list-,get-"）

--exclude — 逗号分隔的 glob 模式以黑名单工具（例如 "delete-*"）

--methods — 逗号分隔的 HTTP 方法以允许（例如 "GET,POST"，仅限 OpenAPI）

配置存储在 ~/.config/mcp2cli/baked.json 中。使用 MCP2CLI_CONFIG_DIR 覆盖。

使用感知的工具排名

mcp2cli 在本地跟踪工具调用，并使用该数据对 --list 输出进行排名，减少 LLM agent 与大型服务器一起工作的 token 成本。

# Default --list: ~1,400 tokens for 96 tools
mcp2cli @myapi --list

# Top 10 most-used tools, names only: ~20 tokens
mcp2cli @myapi --list --top 10 --compact

# Sort by most recently used
mcp2cli @myapi --list --sort recent

# Alphabetical sort
mcp2cli @myapi --list --sort alpha

当存在源的使用数据时，--list 默认按调用频率排序。否则保留插入顺序。使用数据存储在 ~/.cache/mcp2cli/usage.json 中。

JSON 输出

--json 为每个命令、在每个模式中都在 stdout 上强制有效的 JSON。它是人类格式默认输出的机器可读对应物，设计用于需要可靠地解析结果的 LLM agent 和脚本。

# --list emits a JSON array of command objects (name, description, parameters, ...)
mcp2cli --mcp https://mcp.example.com/sse --list --json
mcp2cli --spec ./openapi.json --list --json
mcp2cli --graphql https://api.example.com/graphql --list --json

# --list --json --compact emits a JSON array of names only
mcp2cli --mcp https://mcp.example.com/sse --list --json --compact

# MCP tool calls emit the FULL CallToolResult envelope — including
# structuredContent and isError, not just the flattened text. This surfaces the
# machine-readable result that modern MCP tools put in structuredContent.
mcp2cli --mcp https://mcp.example.com/sse --json search --query "test"
# { "content": [...], "structuredContent": {...}, "isError": false }

# OpenAPI / GraphQL calls emit the response as JSON (non-JSON bodies become a JSON string)
mcp2cli --spec ./openapi.json --json list-pets
mcp2cli --graphql https://api.example.com/graphql --json users

--json 优先于 --raw 和 --toon（两者都可能产生非 JSON），因此它总是赢 —— 这就是使其成为可靠的"强制 JSON"开关的原因。缩进遵循通常的规则：在 TTY 或使用 --pretty 时漂亮打印，管道时紧凑。

# Pretty-print JSON (also auto-enabled for TTY)
mcp2cli --spec ./spec.json --pretty list-pets

# Raw response body (no JSON parsing)
mcp2cli --spec ./spec.json --raw get-data

# Truncate large responses to first N records
mcp2cli --spec ./spec.json list-records --head 5

# Pipe-friendly (compact JSON when not a TTY)
mcp2cli --spec ./spec.json list-pets | jq '.[] | .name'

# TOON output — token-efficient encoding for LLM consumption
# Best for large uniform arrays (40-60% fewer tokens than JSON)
mcp2cli --mcp https://mcp.example.com/sse --toon list-tags

缓存

规范和 MCP 工具列表被缓存在 ~/.cache/mcp2cli/ 中，默认 TTL 为 1 小时。

# Force refresh
mcp2cli --spec https://api.example.com/spec.json --refresh --list

# Custom TTL (seconds)
mcp2cli --spec https://api.example.com/spec.json --cache-ttl 86400 --list

# Custom cache key
mcp2cli --spec https://api.example.com/spec.json --cache-key my-api --list

# Override cache directory
MCP2CLI_CACHE_DIR=/tmp/my-cache mcp2cli --spec ./spec.json --list

本地文件规范从不缓存。

完整的命令行参考

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)
  --graphql URL         GraphQL endpoint URL

Options:
  --auth-header K:V       HTTP header (repeatable, value supports env:/file: prefixes)
  --base-url URL          Override base URL from spec
  --transport TYPE        MCP HTTP transport: auto|sse|streamable (default: auto)
  --env KEY=VALUE         Env var for MCP stdio server (repeatable)
  --oauth                 Enable OAuth (authorization code + PKCE flow)
  --oauth-client-id ID    OAuth client ID (supports env:/file: prefixes)
  --oauth-client-secret S OAuth secret (supports env:/file: prefixes)
  --oauth-scope SCOPE     OAuth scope(s) to request
  --cache-key KEY         Custom cache key
  --cache-ttl SECONDS     Cache TTL (default: 3600)
  --refresh               Bypass cache
  --list                  List available subcommands
  --search PATTERN        Search tools by name or description (implies --list)
  --sort MODE             Sort --list output: usage|recent|alpha|default
  --top N                 Show only the top N tools in --list output
  --compact               Space-separated tool names only, no descriptions
  --verbose               Show full tool descriptions (unwrapped)
  --fields FIELDS         Override GraphQL selection set (e.g. "id name email")
  --pretty                Pretty-print JSON output
  --raw                   Print raw response body
  --json                  Force valid JSON output for every command (--list and tool
                          calls). MCP calls emit the full result envelope including
                          structuredContent. Takes precedence over --raw and --toon.
  --toon                  Encode output as TOON (token-efficient for LLMs)
  --head N                Limit output to first N records (arrays)
  --version               Show version

Bake mode:
  bake create NAME [opts]   Save connection settings as a named tool
  bake list                 List all baked tools
  bake show NAME            Show config (secrets masked)
  bake update NAME [opts]   Update a baked tool
  bake remove NAME          Delete a baked tool
  bake install NAME         Create ~/.local/bin wrapper script
  @NAME [args]              Run a baked tool (e.g. mcp2cli @petstore --list)

子命令及其标志由规范或 MCP 服务器工具定义动态生成。运行 <subcommand> --help 获取详细信息。

关于 token 节省分析、架构细节和与 Anthropic 的 Tool Search 的比较，请参阅 OCAI 博客上的完整文章。

开发

# Install with test + MCP deps
uv sync --extra test

# Run tests (96 tests covering OpenAPI, MCP stdio, MCP HTTP, caching, and token savings)
uv run pytest tests/ -v

# Run just the token savings tests
uv run pytest tests/test_token_savings.py -v -s

鸣谢

mcp2cli 建立在 Kagan Yilmaz 的 CLIHub 想法基础之上（基于 CLI 的工具访问以提高 token 效率）