MCP 主机客户端配置实战指南:在 Claude Desktop、VS Code、Cursor、Cline 与 Windsurf 中接入 MCP 服务器(mcp-for-beginners)
MCP 主机客户端配置实战指南:在 Claude Desktop、VS Code、Cursor、Cline 与 Windsurf 中接入 MCP 服务器(mcp-for-beginners)
本指南来自开源课程 mcp-for-beginners 的 Module 3 实战章节,系统讲解如何在五大主流 AI 主机应用中配置并消费 MCP 服务器:Claude Desktop、VS Code(配合 GitHub Copilot)、Cursor、Cline 与 Windsurf。读完本文,你将掌握各主机差异化的 JSON 配置方式、stdio 与 Streamable HTTP 传输机制的选择逻辑、常见故障排查方法以及安全配置底线,能够把已构建的 MCP 服务器(参考 03-GettingStarted/01-first-server/README.md)快速接入日常使用的 AI 工具链。
什么是 MCP 主机(MCP Host)
MCP 主机(MCP Host) 是一个能够连接 MCP 服务器并借此扩展自身能力的 AI 应用程序。可以把它理解为用户直接交互的"前端",而 MCP 服务器则作为提供工具与数据的"后端"。主机是对话、命令与工具的汇聚点:用户在主机中输入自然语言,主机负责发现服务器上注册的 Resources(资源)、Tools(工具)与 Prompts(提示词),再在合适的时机调用它们。
下图展示了用户、MCP 主机与多台 MCP 服务器之间的一对多连接关系,以及本文将要覆盖的五种流行主机:
flowchart LR
User[👤 用户] --> Host[🖥️ MCP 主机]
Host --> S1[MCP 服务器 A]
Host --> S2[MCP 服务器 B]
Host --> S3[MCP 服务器 C]
subgraph "流行主机"
H1[Claude Desktop]
H2[VS Code]
H3[Cursor]
H4[Cline]
H5[Windsurf]
end
每一种主机都有自己的配置方式,但一旦配置完成,它们都通过标准化的 MCP 协议与服务器通信,这正是协议标准化的价值所在:同一台服务器可以被任意兼容主机消费,无需为每个客户端定制接口。
前提条件
在开始配置主机之前,需要准备好以下三项:
- 一台可连接的 MCP 服务器:如果还没有,请先完成 Module 3.1 - 构建你的第一个 MCP 服务器,该模块提供了 C#、Java、Python、TypeScript 与 Rust 五种语言的完整建服步骤。
- 已安装的主机应用程序:根据下文对应小节,在系统上安装 Claude Desktop、VS Code、Cursor、Cline 或 Windsurf。
- 对 JSON 配置文件的基本了解:几乎所有主机都通过 JSON 文件声明服务器条目,理解字段层级与语法是排错的第一步。
先理解传输机制与协议版本(决定配置写法)
在动手配置之前,有必要先厘清两个影响配置写法的基础概念。当前仓库的课程内容基于 MCP 规范的两个版本展开:2025-11-25(旧版)与 2026-07-28(当前正式版)。关于两者的差异,可参阅 01-CoreConcepts/mcp-2026-07-28.md:
2026-07-28将协议层改造为无状态(stateless):移除了initialize/initialized握手与Mcp-Session-Id头,每个请求通过MCP-Protocol-Version、Mcp-Method等请求头自包含全部信息。- 独立 SSE(Server-Sent Events)传输已被弃用,远程场景统一使用 Streamable HTTP。凡是配置指向
/sse的条目(例如 VS Code 的"type": "sse"、url: "http://localhost:8080/sse"),在2026-07-28下均属于 legacy 兼容写法;新项目应在支持 Streamable HTTP 的主机中选择该传输,并使用服务器实际配置的端点。
这也解释了为何下文 Claude Desktop 与 Cursor 的 mcpServers 条目仅需 command/args(对应本地 stdio 子进程),而 VS Code 会出现 type 与 url 字段(对应远程 HTTP)。stdio 适合由主机拉起的本地服务器;Streamable HTTP 适合远程服务器或多客户端共享的服务器。仓库中的 03-GettingStarted/05-stdio-server/README.md 与 03-GettingStarted/06-http-streaming/README.md 分别对这两种传输给出了完整的构建与消费指南。
1. Claude Desktop
Claude Desktop 是 Anthropic 的官方桌面应用,原生支持 MCP,适合在本地快速接入自建服务器。
安装
- 从 Claude 官网下载 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 |
示例配置(同时接入 Python、Node.js 与 npx 三种启动方式的服务器):
{
"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"
}
}
}
}
以 calculator 条目为例,仓库中的 03-GettingStarted/samples/python/mcp_calculator_server.py 正是与该写法对应的真实模块:它基于 MCP Python SDK 定义了 CalculatorMCPServer,注册了 add、subtract、multiply、divide 四个工具(工具定义见 L121-L146),并通过 server/discover 同时声明对 2026-07-28 与 2025-11-25 两个协议版本的支持(实现见 L88-L117)。也就是说,只要把该模块所在目录加入 PYTHONPATH,python -m mcp_calculator_server 即可被 Claude Desktop 作为本地子进程拉起。
配置选项字段
| 字段 | 说明 | 示例 |
|---|---|---|
command |
要执行的程序 | "python"、"node"、"npx" |
args |
命令行参数 | ["-m", "my_server"] |
env |
注入给子进程的环境变量 | {"API_KEY": "xxx"} |
cwd |
工作目录 | "/path/to/server" |
其中 env 字段尤为重要:部分主机在拉起子进程时会清洗(sanitize)自身环境变量,显式在 env 中声明是保证密钥与路径配置可靠传递的标准做法。
验证你的配置
- 保存配置文件;
- 完全重启 Claude Desktop(先退出再重新打开);
- 打开一个新对话;
- 查看输入框附近是否出现 🔌 插头图标,表示已连接服务器;
- 用自然语言让 Claude 调用其中一个工具,例如 "Calculate 25 * 48 using the calculator"。
Claude Desktop 故障排查
服务器未显示:
- 用 JSON 校验工具检查配置文件语法;
- 确认
command指向的可执行文件路径正确、在PATH中; - 通过 Help → Show Logs 查看 Claude Desktop 日志。
服务器启动即崩溃:
- 先在终端手动运行服务器,验证它独立可用;
- 确认
env中声明的环境变量正确设置; - 确认所有依赖已安装(Python 用
pip list | grep mcp,Node.js 用npm list @modelcontextprotocol/sdk)。
2. VS Code 与 GitHub Copilot
VS Code 通过 GitHub Copilot Chat 扩展提供 MCP 支持,是开发者日常最常用的 MCP 消费场景之一。仓库中的 03-GettingStarted/04-vscode/README.md 对这一场景有完整讲解,包括通过 code --add-mcp 命令行直接向用户配置写入服务器条目,以及通过 chat.mcp.discovery.enabled 设置开启服务器自动发现。
前提条件
- VS Code 1.99 及以上版本;
- 已安装 GitHub Copilot 扩展;
- 已安装 GitHub Copilot Chat 扩展。
配置
VS Code 使用工作区级 .vscode/mcp.json 或用户级 settings.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"
}
}
}
用户级设置(settings.json):
{
"mcp.servers": {
"global-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-memory"]
}
},
"mcp.enableLogging": true
}
注意:上文 my-database 的 "type": "sse" 与 http://localhost:8080/sse 属于 2025-11-25 时代的 legacy HTTP+SSE 写法;在支持 Streamable HTTP 的 VS Code 版本中,应选择该传输并填写服务器实际提供的端点,具体协议差异见 01-CoreConcepts/mcp-2026-07-28.md。
在 VS Code 中可以通过命令行直接添加服务器,例如:
code --add-mcp "{\"name\":\"my-server\",\"command\": \"uvx\",\"args\": [\"mcp-server-fetch\"]}"
在 VS Code 中使用 MCP
- 打开 Copilot Chat 面板(Ctrl+Shift+I / Cmd+Shift+I);
- 输入
@查看可用的 MCP 工具列表; - 用自然语言调用工具,例如 "Calculate 25 * 48 using the calculator"。
下图展示了 VS Code 中 MCP 的实际使用界面:从选择/新增 MCP 服务器,到为 Agent 会话勾选可用工具,再到将对话模式切换为 Agent:
VS Code 故障排查
MCP 服务器未加载:
- 在 Output 面板中切换到 "MCP" 查看错误日志;
- 重新加载窗口:Ctrl+Shift+P → "Developer: Reload Window";
- 先确认服务器能在终端独立运行,再接入 VS Code。
3. Cursor
Cursor 是 AI-first 的代码编辑器,内置 MCP 支持,配置格式与 Claude Desktop 相似。
安装
- 从 Cursor 官网下载安装;
- 安装后登录账号。
配置
配置文件位置:
- macOS:
~/.cursor/mcp.json - Windows:
%USERPROFILE%\.cursor\mcp.json - Linux:
~/.cursor/mcp.json
示例配置(接入文件系统服务器与 GitHub 服务器):
{
"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"
}
}
}
}
其中 filesystem 服务器的最后一个参数是允许访问的目录白名单,github 服务器则需要通过 env 注入 GITHUB_TOKEN——这正是安全最佳实践中"按最小权限暴露访问范围"的典型例子。
在 Cursor 中使用 MCP
- 打开 Cursor 的 AI 聊天(Ctrl+L / Cmd+L);
- MCP 工具会自动出现在建议中;
- 用自然语言让 AI 基于已连接的服务器完成任务。
4. Cline(终端型客户端)
Cline 是基于终端的 MCP 客户端,适合命令行工作流,可通过环境变量、命令行参数或配置文件三种方式声明服务器。
安装
npm install -g @anthropic/cline
配置
方式一:环境变量
export ANTHROPIC_API_KEY="your-api-key"
export MCP_SERVER_CALCULATOR="python -m mcp_calculator_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 代码编辑器,其配置通过设置界面托管,适合偏好图形化操作的用户。
安装
- 从 Windsurf 官网下载安装;
- 安装后创建账号。
配置
Windsurf 的配置由设置 UI 管理:
- 打开设置(Ctrl+, / Cmd+,);
- 搜索 "MCP";
- 点击 "Edit in settings.json" 进入 JSON 编辑。
示例配置:
{
"windsurf.mcp.servers": {
"my-tools": {
"command": "python",
"args": ["/path/to/server.py"],
"env": {}
}
},
"windsurf.mcp.enabled": true
}
注意 windsurf.mcp.enabled 开关字段:如果启用了 windsurf.mcp.servers 但服务器仍不生效,请先确认该总开关处于开启状态。
传输类型对比
不同主机支持的传输机制存在差异,选择传输前应先对照下表:
| 主机 | stdio | SSE/HTTP | WebSocket |
|---|---|---|---|
| Claude Desktop | ✅ | ❌ | ❌ |
| VS Code | ✅ | ✅ | ❌ |
| Cursor | ✅ | ✅ | ❌ |
| Cline | ✅ | ✅ | ❌ |
| Windsurf | ✅ | ✅ | ❌ |
- stdio(标准输入/输出):最适合由主机拉起的本地服务器,配置只需
command+args,无需网络端点; - SSE/HTTP:适合远程服务器,或需要在多个客户端之间共享的服务器;在新规范下请优先使用 Streamable HTTP 传输。
常见故障排查
服务器无法启动
- 先手动测试服务器,确认它能独立运行:
# 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
服务器已连接但工具不工作
- 检查服务器日志——大多数主机提供日志选项(如 Claude Desktop 的 Help → Show Logs、VS Code 的 Output 面板);
- 验证工具注册——使用 MCP Inspector 连接服务器,检查
tools/list是否返回预期工具、工具调用是否返回预期结果; - 检查权限——部分工具需要文件或网络访问权限,确认服务器进程与主机授予了必要权限。
环境变量未传递给服务器
- 部分主机在拉起子进程时会清洗环境变量;
- 请显式使用配置中的
env字段声明所需变量; - 不要在配置文件中明文存放敏感信息,改用密钥管理系统或主机提供的密钥注入机制。
安全最佳实践
在把任意服务器接入主机之前,请遵循以下五条底线:
- 绝不把 API 密钥提交到配置文件(如 Cursor 示例中的
GITHUB_TOKEN仅用于本地演示); - 敏感数据使用环境变量传递,并通过主机的
env字段显式注入; - 按最小权限原则限制服务器权限,只授予完成任务所需的文件与网络访问范围(如
server-filesystem的白名单目录); - 在授予系统访问权之前审查服务器代码,确认其行为符合预期;
- 对文件系统与网络访问使用白名单(allowlist),缩小攻击面。
下一步学习路径
完成本模块后,建议按以下顺序继续深入:
- Module 3.13 - 使用 MCP Inspector 调试:学习在接入主机前如何独立验证服务器的工具、资源与提示词;
- Module 3.1 - 构建你的第一个 MCP 服务器:从零搭建五种语言的服务器实现;
- Module 5 - 高级主题:深入传输、安全、扩展性与生产部署。
仓库中的示例代码(如 Python 计算器服务器)均可直接作为被主机消费的候选服务器,配合本指南的配置方法即可完成从"写完服务器"到"在 AI 应用里用起来"的完整闭环。


