使用说明
联合国儿童基金会
跳过MCP。享受CLI。
直接从终端使用MCP服务器工具。非常适合脚本、自动化和代理工作流。
兼容性： 预计可以开箱即用地与大多数MCP服务器配合使用——只需将其指向任何基于stdio的MCP服务器即可。
快速开始
# 1. Configure your MCP servers in .unmcp/.mcp.json
# 2. Initialize a server (discovers available tools)
uvx unmcp clt init <server>
# 3. Call tools directly
uvx unmcp <server> <tool> [OPTIONS]
为什么是unmcp？
MCP服务器提供强大的结构化工具。但是MCP协议将大型工具模式和详细数据加载到AI上下文中——令牌昂贵，实践缓慢。
CLI更精简。它避免了将工具模式和冗长的输出加载到模型上下文中。
unmcp允许您通过CLI直接访问MCP服务器工具。相同的工具，没有协议开销。
并非所有MCP服务器都有官方CLI。unmcp允许您立即将现有的MCP服务器用作CLI，而不是等待。
看 剧作家CLI与MCP 出于类似的动机。
用法
服务器管理
uvx unmcp clt init <server> # Initialize and discover tools (--force to reinitialize)
uvx unmcp clt list # List servers with status
uvx unmcp clt start <server> # Start persistent daemon
uvx unmcp clt stop <server> # Stop daemon
呼叫工具
参数名称与MCP工具模式完全匹配（例如。， libraryId 成为 --libraryId).
# Basic call
uvx unmcp <server> <tool> --arg1 "value"
# Output as JSON (flag before tool name)
uvx unmcp <server> --json <tool> --arg1 "value"
# Save to file (flag before tool name)
uvx unmcp <server> --output result.json <tool> --arg1 "value"
# Save to directory (auto-generates filename: {server}_{tool}_{timestamp}.json)
uvx unmcp <server> --output ./output_dir/ <tool> --arg1 "value"
# View available tools
uvx unmcp <server> --help
# View tool options
uvx unmcp <server> <tool> --help
执行模式
按需模式
每次工具调用都会生成一个新的MCP服务器，执行该工具，然后退出。
何时使用： MCP服务器启动很快，工具调用不频繁，或者服务器是无状态的。避免保持额外进程运行。
sequenceDiagram
participant CLI as uvx unmcp
participant MCP as MCP Server
CLI->>MCP: spawn process
CLI->>MCP: initialize + call_tool()
MCP-->>CLI: result
CLI->>MCP: exit
守护程序模式
守护进程使MCP服务器保持运行。工具调用通过Unix套接字连接。
何时使用： 连续进行许多工具调用，服务器启动缓慢，或者服务器在调用之间保持状态。
sequenceDiagram
participant CLI as uvx unmcp
participant D as Daemon
participant MCP as MCP Server
Note over CLI,MCP: uvx unmcp clt start
D->>MCP: spawn & initialize
D->>D: listen on socket
Note over CLI,MCP: uvx unmcp <server> <tool>
CLI->>D: call via socket
D->>MCP: call_tool()
MCP-->>D: result
D-->>CLI: result
Note over CLI,MCP: uvx unmcp clt stop
CLI->>D: shutdown
D->>MCP: close
配置
MCP服务器配置(.unmcp/.mcp.json)
遵循标准MCP配置格式。根据需要添加尽可能多的服务器（本地或全局 ~/.unmcp/.mcp.json):
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "@anthropic/chrome-devtools-mcp@latest"]
},
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
}
}
}
特性
自动倾卸
自动将大量输出保存到文件中，保持代理上下文（和您的终端）干净。
在中配置 .unmcp/.settings.json:
{
"dump_dir": "unmcp_output",
"servers": {
"context7": {
"dump_threshold": 500
}
}
}
当响应超过 dump_threshold 令牌（1个令牌≈4个字符），保存到 dump_dir 而不是印刷。设置为 0 总是倾倒。
对于小响应，转储到文件会增加开销——从文件读取可能比直接接收结果花费更多。设置一个对您的工作流程有意义的阈值。看 用例：上下文7.
在转储中包含调用参数
将工具调用参数添加到转储文件中，以实现可追溯性。
{
"dump_call_args": true
}
当AI代理提取在运行过程中不会改变的数据（如文档）时很有用。转储成为代理可以引用回的缓存，而无需重新获取。
也可以通过以下方式为每台服务器设置 servers.<name>.dump_call_args.
用例：上下文7
背景7 是一个MCP服务器，它为库（React、Next.js等）提取最新的文档和代码示例。它输出 5000+代币 每个查询——非常适合上下文，在反复加载到AI提示中时成本很高。
问题： 每个查询都会将数千个令牌转储到AI的上下文窗口中。如果没有仔细的上下文管理（如子代理或常规压缩），上下文窗口将受到影响。
设置
// .unmcp/.mcp.json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
}
}
}
// .unmcp/.settings.json
{
"servers": {
"context7": {
"dump_threshold": 500,
"dump_call_args": true
}
}
}
用法
我们在这里使用按需模式，因为Context7在调用之间不保存有意义的状态——它只是获取文档。对于像Chrome DevTools MCP（维护浏览器会话状态）这样的有状态服务器，守护进程模式将是更好的选择。
# Initialize
uvx unmcp clt init context7
# Query docs - automatically saved to feature-x-tmp/
uvx unmcp context7 --output feature-x-tmp query-docs --libraryId "/vercel/next.js" --query "app router"
$ uvx unmcp context7 --help
Usage: unmcp context7 [OPTIONS] COMMAND [ARGS]...
Tools for context7 server
Options:
--json Output raw JSON response.
--output PATH Write JSON result to file.
--help Show this message and exit.
Commands:
query-docs Retrieves and queries up-to-date documentation and...
resolve-library-id Resolves a package/product name to a...
$ uvx unmcp context7 --output feature-x-tmp query-docs --libraryId /vercel/next.js --query "How to set up authentication with JWT"
Tool executed successfully.
Tool output written to: feature-x-tmp/context7_query-docs_20260131_194608.json
// feature-x-tmp/context7_query-docs_20260131_194608.json
{
"tool_call": {
"server": "context7",
"tool": "query-docs",
"arguments": {
"libraryId": "/vercel/next.js",
"query": "How to set up authentication with JWT"
}
},
"response": {
"content": [
{
"type": "text",
"text": "### Encrypt and Decrypt Sessions with Jose in Next.js\n\n
Source: https://github.com/vercel/next.js/blob/canary/docs/...\n\n
Implements JWT-based session encryption and decryption using
the Jose library with HS256 algorithm...\n\n
```typescript\nimport 'server-only'\nimport { SignJWT, jwtVerify }
from 'jose'\n...```\n\n
--------------------------------\n\n
### Set Encrypted Session Cookie in Next.js...\n\n
... (5000+ tokens of documentation)"
}
],
"isError": false
}
}
随着 dump_call_args: true，输出包括确切的工具调用参数。这将输出文件转换为AI代理可以引用的缓存，无需在会话期间重新获取相同的文档。
$ uvx unmcp context7 query-docs --help
Usage: unmcp context7 query-docs [OPTIONS]
Retrieves and queries up-to-date documentation and code examples from
Context7 for any programming library or framework.
You must call 'resolve-library-id' first to obtain the exact
Context7-compatible library ID required to use this tool, UNLESS the user
explicitly provides a library ID in the format '/org/project' or
'/org/project/version' in their query.
IMPORTANT: Do not call this tool more than 3 times per question. If you
cannot find what you need after 3 calls, use the best information you have.
Options:
--libraryId TEXT Exact Context7-compatible library ID (e.g.,
'/mongodb/docs', '/vercel/next.js', '/supabase/supabase',
'/vercel/next.js/v14.3.0-canary.87') retrieved from
'resolve-library-id' or directly from user query in the
format '/org/project' or '/org/project/version'.
[required]
--query TEXT The question or task you need help with. Be specific and
include relevant details. Good: 'How to set up
authentication with JWT in Express.js' or 'React useEffect
cleanup function examples'. Bad: 'auth' or 'hooks'.
IMPORTANT: Do not include any sensitive or confidential
information such as API keys, passwords, credentials, or
personal data in your query. [required]
--help Show this message and exit.
随着 dump_threshold: 0，每个Context7响应都保存到 docs_output/，保持您的AI上下文简洁，同时保留完整的文档访问权限。
状态
正在积极发展中。
许可证
麻省理工学院
