配置你的第一个 MCP Server

文档摘要

配置你的第一个 MCP Server

本节摘要:MCP 的配置本质上就是告诉 IDE「去哪里启动哪个 Server 进程、给它什么参数」。不同 IDE 的配置入口和格式略有差异,但核心配置项是相同的:command(启动命令)、args(参数)、env(环境变量)。本节不贴完整 JSON,而是逐项讲清每个配置的含义和作用机制,然后带你验证 Server 是否正常连接。

一、配置入口在哪

IDE	配置位置	格式
Cursor	Settings → MCP → Add Server	JSON 配置文件
VS Code (Copilot)	`.vscode/mcp.json`(项目级)或 Settings	JSON
Windsurf	Settings → MCP Servers	JSON 配置文件
Claude Desktop	`claude_desktop_config.json`	JSON
Cline	扩展设置 → MCP Servers	JSON

虽然入口不同,但配置的核心结构是一样的。

二、核心配置项详解

以 stdio 类型的 Server 为例,关键配置项有三个:

command(必填)

含义:启动 Server 的命令。IDE 会用这个命令创建一个子进程。

常见值:

npx — 运行 npm 包(最常用,不需要全局安装)
node — 直接运行 JS 文件
python / uvx — 运行 Python 包
docker — 在容器中运行

机制:IDE 执行 command + args 组合,启动一个子进程,然后通过 stdin/stdout 与之通信。

args(必填)

含义:传给 command 的参数数组。

示例解读:

["@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
- 第一个参数:npm 包名(npx 会下载并运行这个包)
- 第二个参数:允许访问的目录(白名单)
["-y", "@modelcontextprotocol/server-filesystem", "/path"]
- -y:npx 的自动确认参数(不弹出「是否安装」的提示)

⚠️ 注意:args 中的目录路径是安全白名单。Filesystem Server 只能读写你列出的目录,访问其他路径会被拒绝。不要图方便写 / 或 C:\——那等于把整个磁盘暴露给 AI。

env(可选)

含义:传给 Server 进程的环境变量。通常用于传递 API Key。

典型用途:

BRAVE_API_KEY:搜索 Server 需要的 API 密钥
DATABASE_URL:数据库 Server 的连接字符串
GITHUB_TOKEN:GitHub Server 的访问令牌

机制:这些变量只存在于 Server 子进程的环境中,不会泄露到 IDE 的其他部分。

💡 技巧:敏感的 API Key 建议放在 env 中(而非硬编码在 args 里)。某些 IDE 还支持引用系统环境变量(如 ${env:BRAVE_API_KEY}),避免 Key 明文写在配置文件中。

三、配置实战:Filesystem Server

以 Cursor 为例,配置一个文件系统 Server:

步骤:

打开 Cursor Settings → MCP → Add Server
填写配置:
- Name: filesystem(随便起,用于识别)
- Command: npx
- Args: -y, @modelcontextprotocol/server-filesystem, 你的项目路径
保存,等待状态变为「Connected」(绿色)

验证是否成功:

在 Chat 中问:「列出我项目根目录下的文件」
如果 AI 调用了 list_directory 工具并返回了文件列表 → 配置成功
如果 AI 说「我没有这个工具」→ 检查 Server 状态是否为 Connected

四、配置实战:Search Server

以 Brave Search 为例:

前置:从 Brave Search API 官网获取一个免费 API Key。

配置:

Command: npx
Args: -y, @modelcontextprotocol/server-brave-search
Env: BRAVE_API_KEY = 你的 Key

验证:在 Chat 中问「搜索一下 FastAPI 0.115 有什么新特性」,如果 AI 调用了搜索工具并返回了网页结果 → 成功。

五、常见问题排查

症状	可能原因	解法
Server 状态一直「Starting」	npx 在下载包(首次慢)	等 30 秒;或手动 `npx -y 包名` 预下载
Server 状态「Error」	command 路径不对	确认 `npx` / `node` 在系统 PATH 中
Connected 但 AI 不调用	AI 不知道有这个工具	开新对话(能力在对话开始时注入)
调用时报「permission denied」	目录白名单没配对	检查 args 中的路径是否正确、是否有读写权限
env 中的 Key 不生效	变量名拼错	对照 Server 文档确认变量名(大小写敏感)

💡 技巧:遇到连接问题,第一步永远是看 IDE 的 MCP 面板中 Server 的状态和错误日志。大多数问题都是「路径写错」或「API Key 没配对」。

本节要点回顾

配置本质:告诉 IDE「用什么命令启动哪个 Server、给什么参数」
三个核心项:command(启动命令)、args(参数/白名单)、env(环境变量/API Key)
安全关键:args 中的目录是白名单,不要暴露整个磁盘
验证方法:配置后开新对话,让 AI 执行一个简单操作确认连通
排查思路:看 Server 状态 → 检查 PATH → 检查路径权限 → 检查 Key

配好了 Server,接下来我们用它做点实际的事:让 AI 读写文件、搜索网络。