mcp2cli

Skill by ara.so — MCP Skills collection.

mcp2cli converts any MCP server, OpenAPI specification, or GraphQL endpoint into a CLI at runtime without code generation. It dramatically reduces token consumption by replacing repeated tool schema transmissions with simple CLI calls — saving 96-99% of tokens on every LLM turn.

由ara.so开发的Skill — MCP Skills集合。

mcp2cli可在无需代码生成的情况下，在运行时将任意MCP服务器、OpenAPI规范或GraphQL端点转换为CLI。它通过用简单的CLI调用替代重复的工具架构传输，大幅减少token消耗——在每次LLM交互中节省96-99%的token。

Installation

安装

bash

undefined

bash

undefined

Run directly without installing

无需安装直接运行

uvx mcp2cli --help

Or install globally

或全局安装

uv tool install mcp2cli

Install as a skill for AI agents

作为AI Agent的Skill安装

npx skills add knowsuchagency/mcp2cli --skill mcp2cli

undefined

npx skills add knowsuchagency/mcp2cli --skill mcp2cli

undefined

Core Concepts

核心概念

mcp2cli operates in four modes:

MCP HTTP/SSE: Connect to MCP servers over HTTP with SSE or streamable HTTP transport
MCP stdio: Launch and communicate with local MCP servers via stdio
OpenAPI: Generate CLI from OpenAPI 3.x specs (JSON or YAML)
GraphQL: Introspect and query GraphQL endpoints

All modes support:

Dynamic command generation (no codegen step)
Automatic caching with configurable TTL
OAuth 2.0 flows (authorization code + PKCE, client credentials)
Secret management (env vars, files)
Usage tracking and intelligent tool ranking

mcp2cli支持四种运行模式：

MCP HTTP/SSE：通过HTTP连接MCP服务器，支持SSE或可流式传输的HTTP传输
MCP stdio：启动本地MCP服务器并通过标准输入输出（stdio）通信
OpenAPI：从OpenAPI 3.x规范（JSON或YAML）生成CLI
GraphQL：自动自省（introspect）并查询GraphQL端点

所有模式均支持：

动态命令生成（无需代码生成步骤）
可配置TTL的自动缓存
OAuth 2.0流程（授权码+PKCE、客户端凭证）
密钥管理（环境变量、文件）
使用情况追踪与智能工具排序

MCP HTTP Mode

MCP HTTP模式

Connect to MCP servers over HTTP with automatic transport negotiation:

bash

undefined

通过HTTP连接MCP服务器，自动协商传输方式：

bash

undefined

List available tools

列出可用工具

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

Call a tool

调用工具

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

With authentication

带认证

mcp2cli --mcp https://mcp.example.com/sse
--auth-header "x-api-key:env:MCP_API_KEY"
query --sql "SELECT * FROM users LIMIT 10"

Force specific transport (skip auto-negotiation)

强制指定传输方式（跳过自动协商）

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

Search tools by name or description

按名称或描述搜索工具

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

undefined

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

undefined

MCP stdio Mode

MCP stdio模式

Launch local MCP servers and communicate via stdio:

bash

undefined

启动本地MCP服务器并通过标准输入输出通信：

bash

undefined

List tools from filesystem MCP server

列出文件系统MCP服务器的工具

mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" --list

Read a file

读取文件

mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp"
read-file --path /tmp/data.json

Pass environment variables to the server

向服务器传递环境变量

mcp2cli --mcp-stdio "node ./custom-server.js"
--env DATABASE_URL=env:DATABASE_URL
--env DEBUG=1
search --query "test"

undefined

mcp2cli --mcp-stdio "node ./custom-server.js"
--env DATABASE_URL=env:DATABASE_URL
--env DEBUG=1
search --query "test"

undefined

OpenAPI Mode

OpenAPI模式

Generate CLI from OpenAPI specifications:

bash

undefined

从OpenAPI规范生成CLI：

bash

undefined

Remote spec

远程规范

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

Local spec with base URL override

本地规范并覆盖基础URL

mcp2cli --spec ./openapi.yaml --base-url https://api.example.com --list

Call an endpoint

调用端点

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

POST with JSON body from stdin

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

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

With authentication

带认证

mcp2cli --spec ./openapi.json
--auth-header "Authorization:Bearer env:API_TOKEN"
create-item --name "New Item"

undefined

mcp2cli --spec ./openapi.json
--auth-header "Authorization:Bearer env:API_TOKEN"
create-item --name "New Item"

undefined

GraphQL Mode

GraphQL模式

Query GraphQL endpoints with automatic introspection:

bash

undefined

通过自动自省查询GraphQL端点：

bash

undefined

List all queries and mutations

列出所有查询和变更操作

mcp2cli --graphql https://api.example.com/graphql --list

Execute a query (auto-generates selection set)

执行查询（自动生成选择集）

mcp2cli --graphql https://api.example.com/graphql users --limit 10

Execute a mutation

执行变更操作

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

Override selection set fields

覆盖选择集字段

mcp2cli --graphql https://api.example.com/graphql
users --fields "id name email createdAt"

With authentication

带认证

mcp2cli --graphql https://api.example.com/graphql
--auth-header "Authorization:Bearer env:GRAPHQL_TOKEN"
users

undefined

mcp2cli --graphql https://api.example.com/graphql
--auth-header "Authorization:Bearer env:GRAPHQL_TOKEN"
users

undefined

OAuth Authentication

OAuth认证

All modes support OAuth 2.0 flows:

bash

undefined

所有模式均支持OAuth 2.0流程：

bash

undefined

Authorization code + PKCE (opens browser)

授权码+PKCE（打开浏览器）

mcp2cli --mcp https://mcp.example.com/sse --oauth --list mcp2cli --spec https://api.example.com/openapi.json --oauth list-users mcp2cli --graphql https://api.example.com/graphql --oauth users

Client credentials (machine-to-machine)

客户端凭证（机器对机器）

mcp2cli --spec https://api.example.com/openapi.json
--oauth-client-id "env:OAUTH_CLIENT_ID"
--oauth-client-secret "env:OAUTH_CLIENT_SECRET"
list-resources

With specific scopes

指定权限范围

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

Local spec — provide base URL for OAuth discovery

本地规范——提供OAuth发现的基础URL

mcp2cli --spec ./openapi.json
--base-url https://api.example.com
--oauth
--list


Tokens are cached in `~/.cache/mcp2cli/oauth/` and automatically refreshed.

mcp2cli --spec ./openapi.json
--base-url https://api.example.com
--oauth
--list


Token会缓存到`~/.cache/mcp2cli/oauth/`并自动刷新。

Secret Management

密钥管理

Avoid passing secrets as CLI arguments:

bash

undefined

避免通过CLI参数传递密钥：

bash

undefined

Read from environment variable

从环境变量读取

mcp2cli --mcp https://mcp.example.com/sse
--auth-header "Authorization:env:MY_API_TOKEN"
--list

Read from file

从文件读取

mcp2cli --spec ./openapi.json
--oauth-client-secret "file:/run/secrets/client_secret"
--oauth-client-id "file:/run/secrets/client_id"
--list

Works with secret managers

与密钥管理器配合使用

vault kv get -field=token secret/api |
MY_TOKEN=$(cat) mcp2cli --mcp https://mcp.example.com/sse
--auth-header "Authorization:env:MY_TOKEN"
search --query "data"

undefined

vault kv get -field=token secret/api |
MY_TOKEN=$(cat) mcp2cli --mcp https://mcp.example.com/sse
--auth-header "Authorization:env:MY_TOKEN"
search --query "data"

undefined

Bake Mode — Save Connection Settings

Bake模式——保存连接设置

Create reusable named configurations:

bash

undefined

创建可复用的命名配置：

bash

undefined

Create baked tool from OpenAPI spec

从OpenAPI规范创建预配置工具

mcp2cli bake create petstore
--spec https://api.example.com/openapi.json
--auth-header "Authorization:Bearer env:PETSTORE_TOKEN"
--exclude "delete-,update-"
--methods GET,POST
--cache-ttl 7200

Create baked tool from MCP stdio server

从MCP stdio服务器创建预配置工具

mcp2cli bake create github
--mcp-stdio "npx @modelcontextprotocol/server-github"
--env GITHUB_TOKEN=env:GITHUB_TOKEN
--include "search-,list-"
--exclude "delete-*"

Create baked tool from GraphQL endpoint

从GraphQL端点创建预配置工具

mcp2cli bake create hasura
--graphql https://hasura.example.com/v1/graphql
--auth-header "x-hasura-admin-secret:env:HASURA_SECRET"

Use baked tool with @ prefix

使用@前缀调用预配置工具

mcp2cli @petstore --list mcp2cli @petstore list-pets --limit 5 mcp2cli @github search-repos --query "mcp server" mcp2cli @hasura users --limit 10

Manage baked tools

管理预配置工具

mcp2cli bake list mcp2cli bake show petstore mcp2cli bake update petstore --cache-ttl 3600 mcp2cli bake remove petstore

Install as standalone script

安装为独立脚本

mcp2cli bake install petstore

Creates ~/.local/bin/petstore wrapper

创建~/.local/bin/petstore包装器

Install to custom directory

安装到自定义目录

mcp2cli bake install petstore --dir ./scripts/

undefined

mcp2cli bake install petstore --dir ./scripts/

undefined

Filtering Options

过滤选项

bash

undefined

bash

undefined

Include only specific tool patterns

仅包含特定工具模式

mcp2cli bake create myapi
--spec ./openapi.json
--include "list-,get-,search-*"

Exclude dangerous operations

排除危险操作

mcp2cli bake create myapi
--spec ./openapi.json
--exclude "delete-,destroy-"

Limit to specific HTTP methods (OpenAPI only)

限制为特定HTTP方法（仅OpenAPI）

mcp2cli bake create myapi
--spec ./openapi.json
--methods GET,POST

undefined

mcp2cli bake create myapi
--spec ./openapi.json
--methods GET,POST

undefined

Usage-Aware Tool Ranking

基于使用情况的工具排序

Reduce token costs with intelligent tool ranking:

bash

undefined

通过智能工具排序降低token成本：

bash

undefined

Default list (sorted by usage frequency when available)

默认列表（可用时按使用频率排序）

mcp2cli @myapi --list

Top 10 most-used tools, compact output (~20 tokens)

前10个最常用工具，精简输出（约20个token）

mcp2cli @myapi --list --top 10 --compact

Sort by most recently used

按最近使用排序

mcp2cli @myapi --list --sort recent

Alphabetical sort

按字母顺序排序

mcp2cli @myapi --list --sort alpha

Show full descriptions

显示完整描述

mcp2cli @myapi --list --verbose


Usage data is tracked locally in `~/.cache/mcp2cli/usage.json`.

mcp2cli @myapi --list --verbose


使用数据会在本地追踪并存储于`~/.cache/mcp2cli/usage.json`。

Output Control

输出控制

bash

undefined

bash

undefined

Pretty-print JSON (auto-enabled for TTY)

格式化输出JSON（终端环境自动启用）

mcp2cli --spec ./openapi.json --pretty list-users

Raw response body (no JSON parsing)

原始响应体（不解析JSON）

mcp2cli --spec ./openapi.json --raw get-binary-data

Limit output to first N records

限制输出前N条记录

mcp2cli --spec ./openapi.json list-logs --head 20

TOON output (40-60% fewer tokens for LLMs)

TOON输出（LLM使用时可减少40-60%的token）

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

Pipe-friendly output

便于管道处理的输出

mcp2cli --spec ./openapi.json list-users | jq '.[] | .email'

undefined

mcp2cli --spec ./openapi.json list-users | jq '.[] | .email'

undefined

Caching

缓存

Control spec and tool list caching:

bash

undefined

控制规范和工具列表的缓存：

bash

undefined

Force refresh (bypass cache)

强制刷新（绕过缓存）

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

Custom TTL (7 days)

自定义TTL（7天）

mcp2cli --spec https://api.example.com/openapi.json --cache-ttl 604800 --list

Custom cache key

自定义缓存键

mcp2cli --spec https://api.example.com/openapi.json --cache-key prod-api --list

Override cache directory

覆盖缓存目录

MCP2CLI_CACHE_DIR=/tmp/my-cache mcp2cli --spec ./openapi.json --list


Default cache location: `~/.cache/mcp2cli/`
Default TTL: 3600 seconds (1 hour)

MCP2CLI_CACHE_DIR=/tmp/my-cache mcp2cli --spec ./openapi.json --list


默认缓存位置：`~/.cache/mcp2cli/`
默认TTL：3600秒（1小时）

Common Patterns

常见模式

Create a Skill from an API

从API创建Skill

bash

undefined

bash

undefined

Generate a skill configuration for an OpenAPI service

为OpenAPI服务生成Skill配置

mcp2cli --spec https://api.example.com/openapi.json --list

Create baked tool for easier access

创建预配置工具以便访问

mcp2cli bake create myservice
--spec https://api.example.com/openapi.json
--auth-header "Authorization:Bearer env:MYSERVICE_TOKEN"

Use in skill workflows

在Skill工作流中使用

mcp2cli @myservice list-resources --format json | jq '.[] | select(.active == true)'

undefined

mcp2cli @myservice list-resources --format json | jq '.[] | select(.active == true)'

undefined

Multi-Environment Setup

多环境配置

bash

undefined

bash

undefined

Development environment

开发环境

mcp2cli bake create myapi-dev
--spec https://dev-api.example.com/openapi.json
--auth-header "Authorization:Bearer env:DEV_TOKEN"

Production environment

生产环境

mcp2cli bake create myapi-prod
--spec https://api.example.com/openapi.json
--auth-header "Authorization:Bearer env:PROD_TOKEN"

Use environment-specific tools

使用环境专属工具

mcp2cli @myapi-dev test-endpoint --data "test" mcp2cli @myapi-prod get-metrics --period "24h"

undefined

mcp2cli @myapi-dev test-endpoint --data "test" mcp2cli @myapi-prod get-metrics --period "24h"

undefined

Chaining with MCP Servers

与MCP服务器链式调用

bash

undefined

bash

undefined

Use filesystem MCP to read config, then call API

使用文件系统MCP读取配置，然后调用API

CONFIG=$(mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /etc"
read-file --path /etc/myapp/config.json)

echo "$CONFIG" | jq -r '.api_endpoint' |
xargs -I {} mcp2cli --spec {}/openapi.json --list

undefined

CONFIG=$(mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /etc"
read-file --path /etc/myapp/config.json)

echo "$CONFIG" | jq -r '.api_endpoint' |
xargs -I {} mcp2cli --spec {}/openapi.json --list

undefined

Filtering Large Tool Lists

过滤大型工具列表

bash

undefined

bash

undefined

Search tools related to users

搜索与用户相关的工具

mcp2cli @myapi --search "user"

List only creation operations

仅列出创建类操作

mcp2cli @myapi --list | grep "^create-"

Get compact list of top tools for LLM context

获取精简的常用工具列表用于LLM上下文

mcp2cli @myapi --list --top 20 --compact

undefined

mcp2cli @myapi --list --top 20 --compact

undefined

Python API Usage

Python API使用

While mcp2cli is primarily a CLI tool, you can use its components programmatically:

python

from mcp2cli.openapi import load_spec
from mcp2cli.client import make_request
import asyncio

async def call_api():
    # Load OpenAPI spec
    spec = await load_spec("https://api.example.com/openapi.json")
    
    # Make request
    response = await make_request(
        spec=spec,
        operation_id="listPets",
        params={"limit": 10},
        auth_headers={"Authorization": "Bearer token"}
    )
    
    return response

result = asyncio.run(call_api())

虽然mcp2cli主要是CLI工具，但你也可以通过编程方式使用其组件：

python

from mcp2cli.openapi import load_spec
from mcp2cli.client import make_request
import asyncio

async def call_api():
    # 加载OpenAPI规范
    spec = await load_spec("https://api.example.com/openapi.json")
    
    # 发起请求
    response = await make_request(
        spec=spec,
        operation_id="listPets",
        params={"limit": 10},
        auth_headers={"Authorization": "Bearer token"}
    )
    
    return response

result = asyncio.run(call_api())

Troubleshooting

故障排除

OAuth Flow Fails

OAuth流程失败

bash

undefined

bash

undefined

Clear cached tokens

清除缓存的token

rm -rf ~/.cache/mcp2cli/oauth/

Retry with verbose output

启用详细输出重试

mcp2cli --spec ./openapi.json --oauth --list --verbose

undefined

mcp2cli --spec ./openapi.json --oauth --list --verbose

undefined

MCP Server Connection Issues

MCP服务器连接问题

bash

undefined

bash

undefined

Test transport explicitly

显式测试传输方式

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

Check server logs if using stdio

如果使用stdio，检查服务器日志

mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp"
--env DEBUG=*
--list

undefined

mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp"
--env DEBUG=*
--list

undefined

Cache Issues

缓存问题

bash

undefined

bash

undefined

Force refresh

强制刷新

mcp2cli --spec ./openapi.json --refresh --list

Clear all cache

清除所有缓存

rm -rf ~/.cache/mcp2cli/

Use temporary cache location

使用临时缓存位置

MCP2CLI_CACHE_DIR=/tmp/test-cache mcp2cli --spec ./openapi.json --list

undefined

MCP2CLI_CACHE_DIR=/tmp/test-cache mcp2cli --spec ./openapi.json --list

undefined

Tool Not Found After Baking

预配置工具创建后找不到

bash

undefined

bash

undefined

Check baked tool exists

检查预配置工具是否存在

mcp2cli bake list

Verify configuration

验证配置

mcp2cli bake show myapi

Recreate with explicit filters

使用显式过滤重新创建

mcp2cli bake update myapi --include "*"

undefined

mcp2cli bake update myapi --include "*"

undefined

Large Response Truncation

大响应被截断

bash

undefined

bash

undefined

Use --head to limit records

使用--head限制记录数

mcp2cli @myapi list-all --head 100

Use --raw to get full response

使用--raw获取完整响应

mcp2cli @myapi list-all --raw > output.json

Use TOON for token efficiency

使用TOON提升token效率

mcp2cli @myapi list-all --toon

undefined

mcp2cli @myapi list-all --toon

undefined

Configuration

配置

Configuration directory:

~/.config/mcp2cli/

Cache directory:

~/.cache/mcp2cli/

Override with environment variables:

```
MCP2CLI_CONFIG_DIR
```
: Configuration directory
```
MCP2CLI_CACHE_DIR
```
: Cache directory

Baked tools are stored in

~/.config/mcp2cli/baked.json

Usage tracking in

~/.cache/mcp2cli/usage.json

OAuth tokens in

~/.cache/mcp2cli/oauth/

配置目录：

~/.config/mcp2cli/

缓存目录：

~/.cache/mcp2cli/

可通过环境变量覆盖：

```
MCP2CLI_CONFIG_DIR
```
: 配置目录
```
MCP2CLI_CACHE_DIR
```
: 缓存目录

预配置工具存储于

~/.config/mcp2cli/baked.json

使用情况追踪存储于

~/.cache/mcp2cli/usage.json

OAuth token存储于

~/.cache/mcp2cli/oauth/

mcp2cli-api-to-cli

Original

Translation

mcp2cli

mcp2cli

Installation

安装

Run directly without installing

无需安装直接运行

Or install globally

或全局安装

Install as a skill for AI agents

作为AI Agent的Skill安装

Core Concepts

核心概念

MCP HTTP Mode

MCP HTTP模式

List available tools

列出可用工具

Call a tool

调用工具

With authentication

带认证

Force specific transport (skip auto-negotiation)

强制指定传输方式（跳过自动协商）

Search tools by name or description

按名称或描述搜索工具

MCP stdio Mode

MCP stdio模式

List tools from filesystem MCP server

列出文件系统MCP服务器的工具

Read a file

读取文件

Pass environment variables to the server

向服务器传递环境变量

OpenAPI Mode

OpenAPI模式

Remote spec

远程规范

Local spec with base URL override

本地规范并覆盖基础URL

Call an endpoint

调用端点

POST with JSON body from stdin

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

With authentication

带认证

GraphQL Mode

GraphQL模式

List all queries and mutations

列出所有查询和变更操作

Execute a query (auto-generates selection set)

执行查询（自动生成选择集）

Execute a mutation

执行变更操作

Override selection set fields

覆盖选择集字段

With authentication

带认证

OAuth Authentication

OAuth认证

Authorization code + PKCE (opens browser)

授权码+PKCE（打开浏览器）

Client credentials (machine-to-machine)

客户端凭证（机器对机器）

With specific scopes

指定权限范围

Local spec — provide base URL for OAuth discovery

本地规范——提供OAuth发现的基础URL

Secret Management

密钥管理

Read from environment variable

从环境变量读取

Read from file

从文件读取

Works with secret managers

与密钥管理器配合使用

Bake Mode — Save Connection Settings

Bake模式——保存连接设置

Create baked tool from OpenAPI spec