mcp2cli

将任何 MCP 服务器、OpenAPI 规范或 GraphQL 端点在运行时转化为 CLI，无需任何代码生成。
每次调用可节省 96%–99% 的工具模式中浪费的令牌。

阅读完整文章 →

安装

# 无需安装即可直接运行
uvx mcp2cli --help

# 或全局安装
uv tool install mcp2cli

AI 代理技能

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

npx skills add knowsuchagency/mcp2cli --skill mcp2cli

安装后，您可以尝试以下提示：

• mcp2cli --mcp https://mcp.example.com/sse — 与 MCP 服务器交互
• mcp2cli create a skill for https://api.example.com/openapi.json — 从 API 生成技能

使用方法

MCP HTTP/SSE 模式

# 通过 HTTP 连接到 MCP 服务器
mcp2cli --mcp https://mcp.example.com/sse --list

# 调用工具
mcp2cli --mcp https://mcp.example.com/sse search --query "test"

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

# 强制指定特定传输方式（跳过可流式传输的 HTTP 回退流程）
mcp2cli --mcp https://mcp.example.com/sse --transport sse --list

# 按名称或描述搜索工具（不区分大小写的子字符串匹配）
mcp2cli --mcp https://mcp.example.com/sse --search "task"

--search 默认包含 --list，且适用于所有模式（--mcp、--spec、--graphql、--mcp-stdio）。

OAuth 认证

支持需要 OAuth 的 API——无论是在 MCP、OpenAPI 还是 GraphQL 模式下。 mcp2cli 会自动处理令牌获取、缓存和刷新。

# 授权码 + PKCE 流程（打开浏览器进行登录）
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

# 客户端凭证流程（机器对机器，无需浏览器）
mcp2cli --spec https://api.example.com/openapi.json \
  --oauth-client-id "my-client-id" \
  --oauth-client-secret "my-secret" \
  list-pets

# 指定特定作用域
mcp2cli --graphql https://api.example.com/graphql --oauth --oauth-scope "read write" users

# 本地规范文件——使用 --base-url 进行 OAuth 发现
mcp2cli --spec ./openapi.json --base-url https://api.example.com --oauth --list

令牌会持久化保存在 ~/.cache/mcp2cli/oauth/ 中，因此后续调用会复用现有令牌，并在过期时自动刷新。

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

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

# 从环境变量读取
mcp2cli --mcp https://mcp.example.com/sse \
  --auth-header "Authorization:env:MY_API_TOKEN" \
  --list

# 从文件读取
mcp2cli --mcp https://mcp.example.com/sse \
  --oauth-client-secret "file:/run/secrets/client_secret" \
  --oauth-client-id "my-client-id" \
  --list

# 适用于注入环境变量的密钥管理器
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 模式

# 列出 MCP 服务器上的工具
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" --list

# 调用工具
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
  read-file --path /tmp/hello.txt

# 向服务器进程传递环境变量
mcp2cli --mcp-stdio "node server.js" --env API_KEY=sk-... --env DEBUG=1 \
  search --query "test"

OpenAPI 模式

# 列出远程规范中的所有命令
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

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

# 通过标准输入发送 JSON 请求体
echo '{"name": "Fido", "tag": "dog"}' | mcp2cli --spec ./spec.json create-pet --stdin

# 本地 YAML 规范
mcp2cli --spec ./api.yaml --base-url http://localhost:8000 --list

GraphQL 模式

# 列出 GraphQL 端点上的所有查询和突变
mcp2cli --graphql https://api.example.com/graphql --list

# 调用查询
mcp2cli --graphql https://api.example.com/graphql users --limit 10

# 调用突变
mcp2cli --graphql https://api.example.com/graphql create-user --name "Alice" --email "alice@example.com"

# 覆盖自动生成的选择集字段
mcp2cli --graphql https://api.example.com/graphql users --fields "id name email"

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

mcp2cli 会自动检查端点，发现查询和突变，自动生成选择集，并构建带有正确变量声明的参数化查询。无需解析 SDL，无需代码生成——只需指向并运行即可。

Bake 模式——保存连接设置

厌倦了每次调用都要重复 --spec/--mcp/--mcp-stdio 以及认证标志？将它们烘焙成一个命名配置：

# 从 OpenAPI 规范创建烘焙工具
mcp2cli bake create petstore --spec https://api.example.com/spec.json \
  --exclude "delete-*,update-*" --methods GET,POST --cache-ttl 7200

# 从 MCP stdio 服务器创建烘焙工具
mcp2cli bake create mygit --mcp-stdio "npx @mcp/github" \
  --include "search-*,list-*" --exclude "delete-*"

# 使用带 @ 前缀的烘焙工具——无需连接标志
mcp2cli @petstore --list
mcp2cli @petstore list-pets --limit 10
mcp2cli @mygit search-repos --query "rust"

# 管理已烘焙工具
mcp2cli bake list                         # 显示所有已烘焙工具
mcp2cli bake show petstore                # 显示配置（密钥已屏蔽）
mcp2cli bake update petstore --cache-ttl 3600
mcp2cli bake remove petstore
mcp2cli bake install petstore             # 创建 ~/.local/bin/petstore 包装脚本
mcp2cli bake install petstore --dir ./scripts/  # 将包装脚本安装到自定义目录

筛选选项：

• --include — 用逗号分隔的 glob 模式，用于白名单工具（例如 "list-*,get-*"）
• --exclude — 用逗号分隔的 glob 模式，用于黑名单工具（例如 "delete-*"）
• --methods — 用逗号分隔的 HTTP 方法，用于允许的请求方法（例如 "GET,POST"，仅适用于 OpenAPI）

配置存储在 ~/.config/mcp2cli/baked.json 中。可通过 MCP2CLI_CONFIG_DIR 进行覆盖。

输出控制

# 格式化输出 JSON（在终端中也会自动启用）
mcp2cli --spec ./spec.json --pretty list-pets

# 原始响应体（不解析 JSON）
mcp2cli --spec ./spec.json --raw get-data

# 使用 jq 过滤 JSON（相比 Python 更适合 JSON 处理）
mcp2cli --spec ./spec.json list-pets --jq '.[].name'
mcp2cli --spec ./spec.json list-pets --jq '[.[] | select(.status == "available")] | length'

# 截取大型响应的前 N 条记录
mcp2cli --spec ./spec.json list-records --head 5
mcp2cli --spec ./spec.json list-records --head 3 --jq '.'  # 先预览再过滤

# 便于管道处理（非终端时使用紧凑 JSON）
mcp2cli --spec ./spec.json list-pets | jq '.[] | .name'

# TOON 输出 — 面向大模型消费的省 token 编码
# 最适合大型均匀数组（比 JSON 少 40%-60% 的 token）
mcp2cli --mcp https://mcp.example.com/sse --toon list-tags

缓存

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

# 强制刷新
mcp2cli --spec https://api.example.com/spec.json --refresh --list

# 自定义 TTL（秒）
mcp2cli --spec https://api.example.com/spec.json --cache-ttl 86400 --list

# 自定义缓存键
mcp2cli --spec https://api.example.com/spec.json --cache-key my-api --list

# 覆盖缓存目录
MCP2CLI_CACHE_DIR=/tmp/my-cache mcp2cli --spec ./spec.json --list

本地文件规范永远不会被缓存。

CLI 参考

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

来源（互斥，必选其一）：
  --spec URL|FILE       OpenAPI 规范（JSON 或 YAML，本地或远程）
  --mcp URL             MCP 服务器 URL（HTTP/SSE）
  --mcp-stdio CMD       MCP 服务器命令（标准输入输出传输）
  --graphql URL         GraphQL 端点 URL

选项：
  --auth-header K:V       HTTP 头部（可重复，值支持 env:/file: 前缀）
  --base-url URL          覆盖规范中的基础 URL
  --transport TYPE        MCP HTTP 传输方式：auto|sse|streamable（默认：auto）
  --env KEY=VALUE         MCP 标准输入输出服务器的环境变量（可重复）
  --oauth                 启用 OAuth（授权码 + PKCE 流程）
  --oauth-client-id ID    OAuth 客户端 ID（支持 env:/file: 前缀）
  --oauth-client-secret S OAuth 客户端密钥（支持 env:/file: 前缀）
  --oauth-scope SCOPE     请求的 OAuth 范围
  --cache-key KEY         自定义缓存键
  --cache-ttl SECONDS     缓存 TTL（默认：3600）
  --refresh               绕过缓存
  --list                  列出可用的子命令
  --search PATTERN        按名称或描述搜索工具（隐含 --list）
  --fields FIELDS         覆盖 GraphQL 选择集（例如 "id name email"）
  --pretty                格式化输出 JSON
  --raw                   打印原始响应体
  --toon                  将输出编码为 TOON（面向大模型的省 token 格式）
  --jq EXPR               通过 jq 表达式过滤 JSON 输出
  --head N                限制输出为前 N 条记录（数组）
  --version               显示版本

烘焙模式：
  bake create NAME [opts]   将连接设置保存为命名工具
  bake list                 列出所有已烘焙工具
  bake show NAME            显示配置（密钥已屏蔽）
  bake update NAME [opts]   更新一个已烘焙工具
  bake remove NAME          删除一个已烘焙工具
  bake install NAME         创建 ~/.local/bin 包装脚本
  @NAME [args]              运行一个已烘焙工具（例如 mcp2cli @petstore --list）

子命令及其标志会根据规范或 MCP 服务器工具定义动态生成。运行 <子命令> --help 查看详细信息。

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

开发

# 安装并包含测试和 MCP 依赖
uv sync --extra test

# 运行测试（96 项测试，涵盖 OpenAPI、MCP 标准输入输出、MCP HTTP、缓存及节省 token）
uv run pytest tests/ -v

# 仅运行节省 token 的测试
uv run pytest tests/test_token_savings.py -v -s

---

许可证

MIT

---

_{mcp2cli 基于 Kagan Yilmaz 的 CLIHub 思想构建（基于 CLI 的工具访问以实现 token 效率）}

mcp2cli 快速上手指南

环境准备

• 系统要求：支持 Linux、macOS 和 Windows（通过 WSL）。
• 前置依赖：
  • Python 3.8 或更高版本
  • uv（推荐使用 uv 包管理器，可加速安装和依赖解析）
  • 如果使用国内网络，建议配置镜像源以加快下载速度。

---

安装步骤

方法一：无需安装直接运行（推荐）

uvx mcp2cli --help

方法二：全局安装（适用于频繁使用）

uv tool install mcp2cli

💡 提示：如果你在国内，可以使用 uv 的镜像源来加速安装。例如：

uvx --index-url https://mirrors.aliyun.com/pypi/simple/ mcp2cli --help

---

基本使用

示例 1：连接 MCP 服务器并列出可用命令

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

示例 2：调用 MCP 服务器的搜索工具

mcp2cli --mcp https://mcp.example.com/sse search --query "test"

示例 3：从 OpenAPI 规范生成 CLI 工具

mcp2cli --spec https://petstore3.swagger.io/api/v3/openapi.json --list

示例 4：调用 OpenAPI 接口

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

示例 5：使用 Bake 模式保存配置（避免重复输入参数）

mcp2cli bake create petstore --spec https://api.example.com/spec.json --methods GET,POST
mcp2cli @petstore list-pets --limit 10

---

以上是 mcp2cli 的快速入门指南，你可以根据实际需求选择不同的模式（MCP、OpenAPI、GraphQL）进行操作。