MCP 主机客户端配置实战指南:在 Claude Desktop、VS Code、Cursor、Cline 与 Windsurf 中接入 MCP 服务器(mcp-for-beginners)

原创2026-10-08 13:26:191,885 阅读
文章标签:教程示例工程MCP 服务MCP Clients人工智能

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,适合在本地快速接入自建服务器。

安装

  1. 从 Claude 官网下载 Claude Desktop 安装包;
  2. 安装后用 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 中声明是保证密钥与路径配置可靠传递的标准做法。

验证你的配置

  1. 保存配置文件;
  2. 完全重启 Claude Desktop(先退出再重新打开);
  3. 打开一个新对话;
  4. 查看输入框附近是否出现 🔌 插头图标,表示已连接服务器;
  5. 用自然语言让 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 设置开启服务器自动发现。

前提条件

  1. VS Code 1.99 及以上版本;
  2. 已安装 GitHub Copilot 扩展;
  3. 已安装 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

  1. 打开 Copilot Chat 面板(Ctrl+Shift+I / Cmd+Shift+I);
  2. 输入 @ 查看可用的 MCP 工具列表;
  3. 用自然语言调用工具,例如 "Calculate 25 * 48 using the calculator"。

下图展示了 VS Code 中 MCP 的实际使用界面:从选择/新增 MCP 服务器,到为 Agent 会话勾选可用工具,再到将对话模式切换为 Agent:

VS Code 中新增与选择 MCP 服务器的界面

为 Copilot Agent 会话选择可用的 MCP 工具

将 Copilot 对话切换为 Agent 模式以调用 MCP 工具

VS Code 故障排查

MCP 服务器未加载:

  • 在 Output 面板中切换到 "MCP" 查看错误日志;
  • 重新加载窗口:Ctrl+Shift+P → "Developer: Reload Window";
  • 先确认服务器能在终端独立运行,再接入 VS Code。

3. Cursor

Cursor 是 AI-first 的代码编辑器,内置 MCP 支持,配置格式与 Claude Desktop 相似。

安装

  1. 从 Cursor 官网下载安装;
  2. 安装后登录账号。

配置

配置文件位置:

  • 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

  1. 打开 Cursor 的 AI 聊天(Ctrl+L / Cmd+L);
  2. MCP 工具会自动出现在建议中;
  3. 用自然语言让 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 代码编辑器,其配置通过设置界面托管,适合偏好图形化操作的用户。

安装

  1. 从 Windsurf 官网下载安装;
  2. 安装后创建账号。

配置

Windsurf 的配置由设置 UI 管理:

  1. 打开设置(Ctrl+, / Cmd+,);
  2. 搜索 "MCP";
  3. 点击 "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 传输。

常见故障排查

服务器无法启动

  1. 先手动测试服务器,确认它能独立运行:
    # Python
    python -m your_server_module
    
    # Node.js
    node /path/to/server/index.js
    
  2. 检查命令路径:尽量使用绝对路径,并确认可执行文件在 PATH 中;
  3. 验证依赖是否安装:
    # Python
    pip list | grep mcp
    
    # Node.js
    npm list @modelcontextprotocol/sdk
    

服务器已连接但工具不工作

  1. 检查服务器日志——大多数主机提供日志选项(如 Claude Desktop 的 Help → Show Logs、VS Code 的 Output 面板);
  2. 验证工具注册——使用 MCP Inspector 连接服务器,检查 tools/list 是否返回预期工具、工具调用是否返回预期结果;
  3. 检查权限——部分工具需要文件或网络访问权限,确认服务器进程与主机授予了必要权限。

环境变量未传递给服务器

  • 部分主机在拉起子进程时会清洗环境变量;
  • 请显式使用配置中的 env 字段声明所需变量;
  • 不要在配置文件中明文存放敏感信息,改用密钥管理系统或主机提供的密钥注入机制。

安全最佳实践

在把任意服务器接入主机之前,请遵循以下五条底线:

  1. 绝不把 API 密钥提交到配置文件(如 Cursor 示例中的 GITHUB_TOKEN 仅用于本地演示);
  2. 敏感数据使用环境变量传递,并通过主机的 env 字段显式注入;
  3. 按最小权限原则限制服务器权限,只授予完成任务所需的文件与网络访问范围(如 server-filesystem 的白名单目录);
  4. 在授予系统访问权之前审查服务器代码,确认其行为符合预期;
  5. 对文件系统与网络访问使用白名单(allowlist),缩小攻击面。

下一步学习路径

完成本模块后,建议按以下顺序继续深入:

仓库中的示例代码(如 Python 计算器服务器)均可直接作为被主机消费的候选服务器,配合本指南的配置方法即可完成从"写完服务器"到"在 AI 应用里用起来"的完整闭环。

登录后查看全文
mcp-for-beginners