mcp-for-beginners 实战指南:在 Claude Desktop、VS Code、Cursor、Cline 与 Windsurf 中配置主流 MCP Host 客户端
mcp-for-beginners 实战指南:在 Claude Desktop、VS Code、Cursor、Cline 与 Windsurf 中配置主流 MCP Host 客户端
本文是 mcp-for-beginners 开源课程「03-GettingStarted / 12-mcp-hosts」的完整展开。你将理解 MCP Host 在 AI 应用生态中的角色,并掌握在 Anthropic Claude Desktop、VS Code(GitHub Copilot)、Cursor、Cline 与 Windsurf 五种主流客户端中注册、启动、测试与排查 MCP 服务器的完整方法,包括 JSON 配置字段、传输类型选型与安全实践,可直接对照仓库中的首个服务器教程落地实操。
什么是 MCP Host?
MCP Host 是能够连接 MCP 服务器以扩展自身能力的 AI 应用程序。可以把 Host 理解为用户直接交互的"前端"(聊天界面、IDE 面板等),而 MCP 服务器则负责提供"后端"的工具与数据。一个 Host 可以同时连接多个服务器,并通过协议为每个服务器维护独立的连接:
flowchart LR
User[👤 用户] --> Host[🖥️ MCP Host]
Host --> S1[MCP 服务器 A]
Host --> S2[MCP 服务器 B]
Host --> S3[MCP 服务器 C]
subgraph "主流 Host"
H1[Claude Desktop]
H2[VS Code]
H3[Cursor]
H4[Cline]
H5[Windsurf]
end
对照仓库核心概念文档中的定义,Host 承担五类职责:编排 AI 模型(执行或调用 LLM 生成响应)、管理客户端关系(为每个服务器创建一个 MCP client)、控制用户界面(对话流程与响应呈现)、执行安全策略(权限与认证约束)、处理用户授权(数据共享与工具执行的审批)。这也是本文所有配置实践背后的统一模型。
前置条件
- 一个可连接的 MCP 服务器,可先完成模块 3.1:创建你的第一个服务器;
- 目标 Host 应用程序已安装到系统;
- 对 JSON 配置文件有基本了解。
版本提示:为什么 /sse 示例是"旧写法"
[!NOTE] 指向
/sse的 Host 配置属于 MCP2025-11-25时期的 HTTP+SSE 旧示例。对于 MCP2026-07-28,应在支持该特性的 Host 中选择 Streamable HTTP 传输,并使用服务器实际配置的端点。
仓库核心概念文档进一步说明:MCP 当前协议版本为 2026-07-28,传输层已无状态化(不再依赖 initialize 握手与协议级会话 ID),官方支持的传输为 stdio(本地进程)与 Streamable HTTP(远程)。因此当你看到旧教程中的 http://localhost:8080/sse 类配置时,应优先改用新服务器提供的 Streamable HTTP 端点。
1. Claude Desktop
Claude Desktop 是 Anthropic 官方桌面应用,原生支持 MCP,是体验 MCP 最直接的 Host。
安装
- 从 claude.ai/download 下载 Claude Desktop;
- 安装并使用 Anthropic 账户登录。
配置文件位置
Claude Desktop 通过 JSON 配置文件定义 MCP 服务器,不同平台的路径如下:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
配置示例
{
"mcpServers": {
"calculator": {
"command": "python",
"args": ["-m", "mcp_calculator_server"],
"env": {
"PYTHONPATH": "/path/to/your/server"
}
},
"weather": {
"command": "node",
"args": ["/path/to/weather-server/build/index.js"]
},
"database": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://user:pass@localhost/mydb"
}
}
}
}
三个条目分别演示了三种常见启动方式:python -m <模块名> 启动 Python 服务器(配合 PYTHONPATH 指定模块搜索路径)、node <脚本路径> 启动已编译的 Node.js 服务器、npx -y <包名> 免安装直接运行 npm 分发的服务器(如 PostgreSQL 官方参考服务器,通过 env 注入数据库连接串)。
配置字段说明
| 字段 | 描述 | 示例 |
|---|---|---|
command |
要执行的可执行程序 | "python"、"node"、"npx" |
args |
命令行参数 | ["-m", "my_server"] |
env |
传递给服务器进程的环境变量 | {"API_KEY": "xxx"} |
cwd |
服务器进程的工作目录 | "/path/to/server" |
字段中
env与cwd是可选项:env用于注入 API Key、数据库连接串等运行期配置;cwd用于服务器依赖相对路径加载资源时的基准目录。
测试你的配置
- 保存配置文件;
- 完全重启 Claude Desktop(退出后重新打开);
- 新建一个对话;
- 观察界面中的 🔌 图标,它表示已连接的服务器;
- 用自然语言让 Claude 调用某个工具(例如"用计算器算一下 25 × 48")。
Claude Desktop 故障排查
服务器未显示:
- 用 JSON 校验工具检查配置文件语法;
- 确认
command的路径正确(建议使用绝对路径); - 查看 Claude Desktop 日志:
Help → Show Logs。
服务器启动即崩溃:
- 先在终端手动运行服务器命令,确认可独立启动;
- 检查环境变量是否设置正确;
- 确认所有依赖已安装。
2. VS Code + GitHub Copilot
VS Code 通过 GitHub Copilot Chat 系列扩展支持 MCP,是开发者日常使用频率最高的 Host 之一。仓库04-vscode 章节有完整的实操演练,本文摘取其核心配置与命令行技巧。
前置条件
- VS Code 1.99+;
- 已安装 GitHub Copilot 扩展;
- 已安装 GitHub Copilot Chat 扩展。
工作区配置:.vscode/mcp.json
在项目根目录创建 .vscode/mcp.json,声明服务器条目:
{
"servers": {
"my-calculator": {
"type": "stdio",
"command": "python",
"args": ["-m", "mcp_calculator_server"]
},
"my-database": {
"type": "sse",
"url": "http://localhost:8080/sse"
}
}
}
注意 type 字段:stdio 表示由 VS Code 启动本地子进程;sse 表示连接远程 HTTP 服务(如上文版本提示所述,新服务器应改用 Streamable HTTP)。仓库04-vscode 章节还演示了最小可运行配置:"hello-mcp": { "command": "node", "args": ["build/index.js"] }。
用户级配置:settings.json
在用户设置中注册的服务器对所有工作区生效:
{
"mcp.servers": {
"global-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-memory"]
}
},
"mcp.enableLogging": true
}
mcp.enableLogging: true 可打开 MCP 日志,便于排错。
启用 MCP 服务器发现
在 VS Code 设置(File → Preferences → Settings)中搜索 MCP,勾选 chat.mcp.discovery.enabled,确保 VS Code 能发现工作区中的 MCP 服务器。
用命令行添加服务器
除了可视化界面,还可以通过 VS Code 的 code 可执行文件直接从终端注册服务器(仓库04-vscode 章节提供):
code --add-mcp "{\"name\":\"my-server\",\"command\": \"uvx\",\"args\": [\"mcp-server-fetch\"]}"
该命令将 JSON 服务器配置写入用户级配置,适合脚本化、可复现的环境初始化。
在 VS Code 中使用 MCP
- 打开 Copilot Chat 面板(
Ctrl+Shift+I/Cmd+Shift+I); - 输入
@查看可用的 MCP 工具列表; - 用自然语言触发工具,例如"用计算器算 25 * 48"。
配置完成后,VS Code 命令面板会出现服务器列表,可随时选择或新增服务器:
在 Agent 模式下,还可以按会话粒度勾选 Copilot 可使用的工具:
VS Code 故障排查
MCP 服务器未加载:
- 查看输出面板 → "MCP" 的错误日志;
- 重载窗口:
Ctrl+Shift+P→Developer: Reload Window; - 先确认服务器能在命令行独立运行。
3. Cursor
Cursor 是 AI 优先的代码编辑器,内置 MCP 支持,配置格式与 Claude Desktop 高度相似。
安装
- 从 cursor.sh 下载 Cursor;
- 安装并登录。
配置
配置文件位置:
- macOS / Linux:
~/.cursor/mcp.json - Windows:
%USERPROFILE%\.cursor\mcp.json
示例配置(本地文件系统服务器 + GitHub 服务器,通过 env 注入访问令牌):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}
server-filesystem 的最后一个参数是允许服务器访问的目录白名单,这是 MCP 权限最小化的典型实践。
在 Cursor 中使用 MCP
- 打开 Cursor 的 AI 对话(
Ctrl+L/Cmd+L); - MCP 工具会自动出现在建议列表中;
- 直接要求 AI 使用已连接服务器完成任务。
4. Cline(终端风格客户端)
Cline 是面向命令行工作流的 MCP 客户端,适合脚本化、自动化场景。
安装
npm install -g @anthropic/cline
配置方式
Cline 支持三种配置途径:
方式一:环境变量
export ANTHROPIC_API_KEY="your-api-key"
export MCP_SERVER_CALCULATOR="python -m mcp_calculator_server"
方式二:命令行参数(每个 --mcp-server 按 名称:命令 格式声明)
cline --mcp-server "calculator:python -m mcp_calculator_server" \
--mcp-server "weather:node /path/to/weather/index.js"
方式三:配置文件 ~/.clinerc
{
"apiKey": "your-api-key",
"mcpServers": {
"calculator": {
"command": "python",
"args": ["-m", "mcp_calculator_server"]
}
}
}
使用 Cline
# 启动交互式会话
cline
# 单次查询并调用 MCP 工具
cline "Calculate the square root of 144 using the calculator"
# 列出可用工具
cline --list-tools
5. Windsurf
Windsurf 是另一款支持 MCP 的 AI 驱动代码编辑器。
安装
- 从 codeium.com/windsurf 下载 Windsurf;
- 安装并创建账号。
配置
Windsurf 通过设置界面管理 MCP:
- 打开设置(
Ctrl+,/Cmd+,); - 搜索 "MCP";
- 点击 "Edit in settings.json" 编辑配置。
{
"windsurf.mcp.servers": {
"my-tools": {
"command": "python",
"args": ["/path/to/server.py"],
"env": {}
}
},
"windsurf.mcp.enabled": true
}
windsurf.mcp.enabled: true 显式启用 MCP 功能;服务器条目结构与 Claude Desktop 一致。
传输类型对比与选型
不同 Host 对传输机制的支持不同:
| Host | stdio | SSE/HTTP | WebSocket |
|---|---|---|---|
| Claude Desktop | ✅ | ❌ | ❌ |
| VS Code | ✅ | ✅ | ❌ |
| Cursor | ✅ | ✅ | ❌ |
| Cline | ✅ | ✅ | ❌ |
| Windsurf | ✅ | ✅ | ❌ |
- stdio(标准输入/输出):最适合由 Host 本地启动的服务器,进程间直接通过 stdin/stdout 交换 JSON-RPC 消息。
- SSE/HTTP:最适合远程服务器,或需要被多个客户端共享的服务器。
仓库stdio 服务器章节补充了 stdio 传输的关键约束:消息必须以换行符分隔且不能内嵌换行;服务器不得向 stdout 写入任何非 MCP 消息;日志应写入 stderr。理解这些约定有助于在配置出错时快速定位——例如服务器把 console.log 写进了 stdout,就会破坏与 Host 的协议通信。
常见故障排查
服务器无法启动
-
先在终端手动测试服务器:
# Python 服务器 python -m your_server_module # Node.js 服务器 node /path/to/server/index.js -
检查命令路径: 尽量使用绝对路径;确认可执行程序在
PATH中。 -
确认依赖:
# Python pip list | grep mcp # Node.js npm list @modelcontextprotocol/sdk
服务器已连接但工具不工作
- 查看服务器日志——大多数 Host 提供日志选项(如 VS Code 的
mcp.enableLogging); - 用 MCP Inspector 验证工具注册:它能图形化列出服务器注册的 tools/resources/prompts 并直接调用测试,相当于"MCP 的 Postman";
- 检查权限——部分工具需要文件系统或网络访问权。
环境变量未传递给服务器
- 部分 Host 会清洗/过滤环境变量;
- 应在配置文件中通过
env字段显式声明; - 不要在配置文件中存放敏感数据,改用密钥管理服务(secrets management)。
安全最佳实践
对照仓库核心概念文档中的安全原则(用户授权与同意、数据隐私保护、工具执行安全、传输安全),在配置 Host 时请遵循:
- 绝不将 API Key 提交到配置文件或版本库;
- 敏感数据使用环境变量注入(配合各 Host 的
env字段); - 限制服务器权限到完成任务所需的最小范围(如文件系统目录白名单);
- 审查服务器代码后再授予其访问本机系统的权限;
- 对文件系统与网络访问使用允许列表。
下一步学习
配置好 Host 之后,建议按以下路径深入:
- 3.13 - 使用 MCP Inspector 调试:验证服务器能力与排查工具调用的利器;
- 3.1 - 创建你的第一个 MCP 服务器:从零构建可接入上述 Host 的服务器;
- 模块 5 - 高级主题:涵盖安全、传输、扩展等进阶方向。
如果你需要在 VS Code 中完成从创建服务器到消费的完整闭环,可直接对照仓库的 04-vscode 实操章节;各语言的可运行服务器示例位于 samples 目录。

