MCP CLI 速查表

概述

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，旨在标准化 AI 应用与外部工具、数据源的连接方式。MCP 服务器对外暴露三类能力：工具（可执行的函数）、资源（数据源）和提示模板（可复用的 prompt 模板）。CLI 工具链主要分为两套：

- Python SDK CLI（pip install mcp[cli]）— 用于开发、运行和注册 MCP 服务器 - mcptools（brew install mcp 或 go install）— 用于与运行中的 MCP 服务器交互

安装与设置

``bash # 安装 Python SDK（含 CLI） pip install mcp[cli]

# 或使用 uv（更快） uv add mcp[cli]

# 安装 mcptools（基于 Go 的客户端 CLI） brew tap f/mcptools && brew install mcp # 或：go install github.com/f/mcptools/cmd/mcptools@latest `

快速开始

`bash # 1. 创建服务器文件 cat > server.py << 'EOF' from mcp.server import MCPServer

mcp = MCPServer("Demo")

@mcp.tool() def add(a: int, b: int) -> int: """Add two numbers.""" return a + b

if __name__ == "__main__": mcp.run() EOF

# 2. 在 Inspector 中开发调试 uv run mcp dev server.py

# 3. 直接通过 stdio 运行 uv run mcp run server.py

# 4. 安装到 Claude Desktop uv run mcp install server.py --name "Demo"

# 5. 列出服务器工具（mcptools） mcp tools npx -y @modelcontextprotocol/server-filesystem ~

# 6. 调用工具 mcp call read_file --params '{"path":"README.md"}' npx -y @modelcontextprotocol/server-filesystem ~ `

服务管理

MCP 服务器的运行、安装和管理命令：

命令

说明

uv run mcp run server.py	直接通过 stdio 运行服务器
uv run mcp run server.py:myapp	运行文件中指定的服务器对象
uv run mcp run server.py --transport streamable-http	以 HTTP 传输模式运行
uv run mcp dev server.py	在 Inspector GUI 中调试
uv run mcp dev server.py --with pandas	开发模式附带额外依赖
uv run mcp install server.py	注册到 Claude Desktop
uv run mcp install server.py --name "MyApp"	使用自定义名称注册
uv run mcp install server.py -v KEY=val -f .env	注册时传递环境变量

工具与资源操作

使用 mcptools 与运行中的 MCP 服务器交互：

命令

说明

mcp tools	列出所有可用工具
mcp call --params '{}'	调用工具并传递 JSON 参数
mcp resources	列出所有可用资源
mcp read-resource	读取指定资源
mcp prompts	列出所有可用提示模板
mcp get-prompt	获取指定提示模板
mcp shell	启动交互式 Shell 会话

server 参数可以是：npx -y @modelcontextprotocol/server-* <参数>、http://host:port 或预配置的别名。

传输配置

传输协议

CLI 标志

适用场景

stdio	默认	本地服务器，子进程方式启动
streamable-http	--transport streamable-http	部署到生产环境
sse	旧版	HTTP 传输（已废弃）

在 mcp.run() 中配置 HTTP 传输选项： `python mcp.run( transport="streamable-http", host="0.0.0.0", port=3001, json_response=True, max_request_body_size=4_194_304, # 4 MiB ) `

配置管理

管理别名和扫描服务器配置：

`bash # 创建常用服务器的别名 mcp alias add myfs npx -y @modelcontextprotocol/server-filesystem ~/

# 列出所有别名 mcp alias list

# 删除别名 mcp alias remove myfs

# 扫描 IDE/Claude 配置中的 MCP 服务器 mcp configs scan

# 在 VS Code 中设置服务器配置 mcp configs set vscode my-server npm run mcp-server `

高级用法

### 交互式 Shell

`bash mcp shell npx -y @modelcontextprotocol/server-filesystem ~ # > tools # > call read_file --params '{"path":"README.md"}' # > format json # > /q `

### Web 管理界面

`bash mcp web --port 8080 http://localhost:3000 `

### 脚手架生成项目

`bash mcp new tool:calculate resource:file prompt:greet `

生成完整的 TypeScript MCP 项目，自动注册组件。

### 模拟服务器测试

`bash mcp mock my-server --tools 5 --resources 3 `

### Python 服务器模板

`python from mcp.server import MCPServer

mcp = MCPServer("MyApp", log_level="DEBUG")

@mcp.tool() def search_books(query: str) -> str: """按书名或作者搜索图书。""" return f"找到 {query!r} 的相关结果。"

@mcp.resource("greeting://{name}") def greeting(name: str) -> str: """个性化问候。""" return f"你好，{name}！"

if __name__ == "__main__": mcp.run() `

### Python 客户端示例

`python import asyncio from mcp import Client

async def main(): async with Client(mcp) as client: # 或 Client("http://host:port") result = await client.call_tool("search_books", {"query": "mcp"}) print(result.structured_content)

asyncio.run(main()) `

常见问题

### 如何更新 MCP SDK？ `bash pip install --upgrade mcp[cli] # 或 uv add --dev mcp[cli]@latest ` v2 预发布版本需要锁定精确版本号：pip install mcp[cli]==2.0.0b1。

### mcp run 找不到我的服务器对象怎么办？ mcp run server.py 导入文件后会查找全局变量中类型为 MCPServer 的对象，变量名可以是 mcp、server 或 app。如果对象名不同，使用 server.py:myobject 语法。mcp run 不会执行 if __name__ == "__main__": 块中的代码。

### 如何调试 MCP 服务器？ - 使用 uv run mcp dev server.py 打开 Inspector GUI - 设置 log_level="DEBUG" 在 MCPServer("Name", log_level="DEBUG") 中 - 日志输出到 stderr（stdout 是 MCP 协议信道——不要使用 print()） - 使用 mcp mock --tools 3 创建模拟服务器进行隔离测试

### VS Code 或 Cursor 能使用 MCP 吗？ 可以。大多数现代 AI 编码工具都支持 MCP。通过编辑器自身的配置（如 VS Code 的 settings.json、Cursor 的 mcp.json）注册服务器，或使用 mcp configs set 命令：mcp configs set cursor my-server npx ...`。