mcp-for-beginners 实战指南:在 Claude Desktop、VS Code、Cursor、Cline 与 Windsurf 中配置主流 MCP Host 客户端

原创2026-10-09 23:29:371,969 阅读
文章标签:教程示例工程MCP 服务MCP Clients人工智能

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)、控制用户界面(对话流程与响应呈现)、执行安全策略(权限与认证约束)、处理用户授权(数据共享与工具执行的审批)。这也是本文所有配置实践背后的统一模型。

前置条件

版本提示:为什么 /sse 示例是"旧写法"

[!NOTE] 指向 /sse 的 Host 配置属于 MCP 2025-11-25 时期的 HTTP+SSE 旧示例。对于 MCP 2026-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。

安装

  1. 从 claude.ai/download 下载 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

配置示例

{
  "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 用于服务器依赖相对路径加载资源时的基准目录。

测试你的配置

  1. 保存配置文件;
  2. 完全重启 Claude Desktop(退出后重新打开);
  3. 新建一个对话;
  4. 观察界面中的 🔌 图标,它表示已连接的服务器;
  5. 用自然语言让 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 章节有完整的实操演练,本文摘取其核心配置与命令行技巧。

前置条件

  1. VS Code 1.99+;
  2. 已安装 GitHub Copilot 扩展;
  3. 已安装 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

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

配置完成后,VS Code 命令面板会出现服务器列表,可随时选择或新增服务器:

在 VS Code 中选择与添加 MCP 服务器

在 Agent 模式下,还可以按会话粒度勾选 Copilot 可使用的工具:

按会话选择可用的 MCP 工具

VS Code 故障排查

MCP 服务器未加载:

  • 查看输出面板 → "MCP" 的错误日志;
  • 重载窗口:Ctrl+Shift+P → Developer: Reload Window;
  • 先确认服务器能在命令行独立运行。

3. Cursor

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

安装

  1. 从 cursor.sh 下载 Cursor;
  2. 安装并登录。

配置

配置文件位置:

  • 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

  1. 打开 Cursor 的 AI 对话(Ctrl+L / Cmd+L);
  2. MCP 工具会自动出现在建议列表中;
  3. 直接要求 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 驱动代码编辑器。

安装

  1. 从 codeium.com/windsurf 下载 Windsurf;
  2. 安装并创建账号。

配置

Windsurf 通过设置界面管理 MCP:

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


常见故障排查

服务器无法启动

  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. 查看服务器日志——大多数 Host 提供日志选项(如 VS Code 的 mcp.enableLogging);
  2. 用 MCP Inspector 验证工具注册:它能图形化列出服务器注册的 tools/resources/prompts 并直接调用测试,相当于"MCP 的 Postman";
  3. 检查权限——部分工具需要文件系统或网络访问权。

环境变量未传递给服务器

  • 部分 Host 会清洗/过滤环境变量;
  • 应在配置文件中通过 env 字段显式声明;
  • 不要在配置文件中存放敏感数据,改用密钥管理服务(secrets management)。

安全最佳实践

对照仓库核心概念文档中的安全原则(用户授权与同意、数据隐私保护、工具执行安全、传输安全),在配置 Host 时请遵循:

  1. 绝不将 API Key 提交到配置文件或版本库;
  2. 敏感数据使用环境变量注入(配合各 Host 的 env 字段);
  3. 限制服务器权限到完成任务所需的最小范围(如文件系统目录白名单);
  4. 审查服务器代码后再授予其访问本机系统的权限;
  5. 对文件系统与网络访问使用允许列表。

下一步学习

配置好 Host 之后,建议按以下路径深入:

如果你需要在 VS Code 中完成从创建服务器到消费的完整闭环,可直接对照仓库的 04-vscode 实操章节;各语言的可运行服务器示例位于 samples 目录。

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