mcptocli (Maxime Rivest)

mcptocli：将任何MCP服务器转换为CLI

📖 文档

如果 mcp2py 将MCP服务器转换为Python模块， mcptocli 将MCP服务器转换为可以从任何终端使用的命令行工具。

什么是MCP？

MCP（模型上下文协议）是一种新兴的标准，它允许人工智能工具、API和本地应用程序以机器可读的方式描述它们可以做什么。越来越多的服务正在公开MCP接口。当他们这样做时，你不必学习他们定制的API——你只需要指出 mcptocli 在他们面前，开始从你的终端使用他们的工具。

你不需要理解协议。 你需要知道的是：

如果服务具有MCP服务器， mcptocli 让您像使用普通的命令行工具一样使用它。

______________________________________________________________________

安装

macOS和Linux

curl -fsSL https://raw.githubusercontent.com/MaximeRivest/mcptocli/main/install.sh | sh

这将为您的平台下载正确的二进制文件，安装它，并设置shell补全——所有这些都在一个步骤中完成。

视窗

irm https://raw.githubusercontent.com/MaximeRivest/mcptocli/main/install.ps1 | iex

验证

打开A 新 终端和运行：

mcptocli version

Manual install (if you prefer)

mcptocli 是一个单一的二进制文件。从以下网址下载适合您平台的版本 发布页面，使其可执行，并将其放入您的 PATH.

______________________________________________________________________

快速开始

两个步骤： 添加 一次服务器，然后 使用 它的名字。

步骤1：添加服务器

mcptocli add time 'uvx mcp-server-time'

就是这样。第二个参数是启动服务器的命令。URL会自动检测：

mcptocli add notion https://mcp.notion.com/mcp --auth oauth

第二步：使用它

mcptocli time tools

Tools (2):

  convert-time      Convert time between timezones.
  get-current-time  Get current time in a specific timezone.

Inspect:  mcptocli tools time 
Invoke:   mcptocli time  [args...]

mcptocli time get-current-time --timezone 'America/New_York'

服务器名称 是 命令。不 tool 对比 tools 记住——只是服务器名称后面跟着你想做的事情。

______________________________________________________________________

日常使用

添加服务器后，您需要的一切如下：

mcptocli time tools                                              # list tools
mcptocli time get-current-time --timezone 'America/New_York'      # call a tool
mcptocli time get-current-time 'Europe/London'                    # positional args work too
mcptocli time resources                                          # list resources
mcptocli time prompts                                            # list prompts
mcptocli time shell                                              # interactive mode
mcptocli time doctor                                             # diagnose problems

在调用工具之前检查它

mcptocli time tools get-current-time

NAME
  get-current-time - Get current time in a specific timezone

USAGE
  time get-current-time --timezone 

ARGS
  --timezone string  Required. IANA timezone name (e.g., 'America/New_York', 'Europe/London').

保持服务器运行以获得即时响应

mcptocli time up                                        # start in background
mcptocli time get-current-time 'America/New_York'        # ~10ms instead of ~2s
mcptocli time get-current-time 'Europe/London'            # instant
mcptocli time down                                       # stop when done

跨多个客户端共享一台服务器

mcptocli time up --share                                # start in HTTP mode
mcptocli time get-current-time 'America/New_York'        # mcptocli uses it automatically
# Other MCP clients (Claude Desktop, notebooks) can connect to the same server
mcptocli time down                                       # stop when done

交互式 shell

mcptocli time shell

time> tools
time> get-current-time 'America/New_York'
time> convert-time --source-timezone 'America/New_York' --time '14:30' --target-timezone 'Europe/London'
time> set output json
time> get-current-time 'Europe/London'
time> exit

shell保持连接打开，支持历史记录和标签完成，并允许您动态切换输出格式。

______________________________________________________________________

远程服务器

使用不记名代币

export ACME_TOKEN="your-api-key"
mcptocli add acme https://api.acme.dev/mcp --bearer-env ACME_TOKEN
mcptocli acme tools
mcptocli acme search --query invoices

使用OAuth（浏览器登录）

mcptocli add notion https://mcp.notion.com/mcp --auth oauth
mcptocli notion tools
# Browser opens automatically the first time

______________________________________________________________________

输出格式

mcptocli time get-current-time 'America/New_York'            # human-readable (default)
mcptocli time get-current-time 'America/New_York' -o json     # exact JSON for scripts
mcptocli time get-current-time 'America/New_York' -o yaml     # YAML

-o json 始终是脚本安全的：输出转到 stdout，诊断转到 stderr，出口代码稳定。

______________________________________________________________________

参数

mcptocli 读取工具的模式并自动生成CLI标志。

# Named flags (always work)
mcptocli time get-current-time --timezone 'America/New_York'

# Positional arguments (for required scalar args, in schema order)
mcptocli time get-current-time 'America/New_York'

# Booleans
mcptocli api update --dry-run
mcptocli api update --no-dry-run

# Repeated values for arrays
mcptocli api search --tag cli --tag go --tag mcp

# Structured JSON from a file
mcptocli api create --payload @data.json

# Or from stdin
cat data.json | mcptocli api create --payload @-

对于复杂的模式，你总是可以回到原始JSON：

mcptocli api complex-tool --input '{"nested": {"key": "value"}}'

______________________________________________________________________

一次性使用（无需注册）

您无需注册服务器即可使用它：

mcptocli tools --command 'uvx mcp-server-time'
mcptocli tool --command 'uvx mcp-server-time' get-current-time 'America/New_York'
mcptocli tool --url https://api.example.com/mcp --bearer-env TOKEN search --query test

______________________________________________________________________

暴露的命令

当您添加服务器时， mcptocli 自动为其创建独立命令：

mcptocli add time 'uvx mcp-server-time'
# → creates mcp-time

mcp-time tools
mcp-time get-current-time 'America/New_York'

想要一个更短的名字吗？

mcptocli expose time --as t
t tools
t get-current-time 'America/New_York'

删除暴露的命令：

mcptocli expose --remove time

这些是你的真实命令 PATH，所以 mcp- 在你的壳里工作。

______________________________________________________________________

管理服务器

mcptocli add time 'uvx mcp-server-time'                        # save
mcptocli ls                                                     # list all
mcptocli rm time                                                # remove (cleans up exposed commands too)

ls 输出：

time (up)  uvx mcp-server-time
notion     https://mcp.notion.com/mcp

配置会自动保存：

• 全球的： ~/.config/mcptocli/config.yaml
• 每个项目： .mcptocli.yaml （使用 --local 旗帜）

______________________________________________________________________

诊断问题

mcptocli time doctor

CHECK    STATUS  DETAIL
resolve  ok      time
command  ok      /home/maxime/.local/bin/uvx
auth     ok      no auth required
connect  ok      initialize handshake succeeded
tools    ok      2 tool(s) available

______________________________________________________________________

壳体完井

# bash
echo 'source > ~/.bashrc

# zsh
echo 'source > ~/.zshrc

# fish
mcptocli completion fish | source

______________________________________________________________________

如何 mcptocli 与...相关 mcp2py

mcp2py 将MCP服务器转变为 Python模块 --非常适合Python中的笔记本电脑、脚本和数据分析。

mcptocli 将MCP服务器转变为 Shell 命令 --非常适合终端用户、shell脚本、CI管道和任何喜欢命令行的人。

它们相辅相成。如果服务有MCP服务器：

• 使用 mcp2py 从Python调用它
• 使用 mcptocli 从bash、zsh、fish、PowerShell或任何终端调用它

______________________________________________________________________

从源代码构建

git clone https://github.com/MaximeRivest/mcptocli.git
cd mcptocli
go build -o mcptocli ./cmd/mcptocli
./mcptocli version

______________________________________________________________________

当前状态

这是一个alpha版本。今天有效的方法：

• ✅ 本地stdio MCP服务器
• ✅ 远程HTTP JSON-RPC MCP服务器
• ✅ 承载令牌和自定义标头身份验证
• ✅ 使用浏览器流和令牌持久性的OAuth登录
• ✅ 工具、资源和提示
• ✅ 模式驱动的CLI标志和位置参数
• ✅ 服务器名称作为隐式子命令(mcptocli time tools)
• ✅ 用于即时响应的后台守护进程(mcptocli time up)
• ✅ 暴露的独立命令(mcp-time, t)
• ✅ 具有历史和完成的交互式shell模式
• ✅ 终端启发（服务器发起的用户提示）
• ✅ 流式HTTP（SSE）传输
• ✅ 用于快速完成的元数据缓存
• ✅ doctor 诊断

仍将到来：

• ✅ 共享HTTP守护进程模式(up --share)
• ⬜ 采样（LLM支持的服务器请求）

______________________________________________________________________

如果 mcp2py 使MCP感觉像一个原生Python库， mcptocli 让MCP感觉它从第一天就为码头而建。