MCP 实战教程：从安装到看见效果（完整实例）

做完本教程，你应该能亲眼看到这三件事（缺一则说明没接通）：

1. 设置里已连接：Cursor → Settings → MCP，该 Server 显示绿色 Connected（或 Tools 数量 > 0）
2. 对话里出现工具调用：如 list_directory / read_file
3. 回复是真实本机数据：文件名或内容来自你磁盘，而不是模型瞎编的路径

本例以 文件系统 MCP 演示；打开任意 MCP 详情页，把「复制配置」换成该页的 Cursor Tab 即可，步骤通用。

实例目标

让 Cursor Agent 能列出并阅读你指定目录里的文件，例如：

• 问：「列出 ~/Documents/demo-mcp 下有哪些文件？」
• 再问：「把其中 README.md 的前 30 行读给我」

你需要

• 已安装 Cursor（建议最新稳定版）
• 本机已装 Node.js（终端执行 node -v 有版本号即可；多数 MCP 用 npx 启动）
• 一个练习目录（不要一上来挂整盘根目录）

mkdir -p ~/Documents/demo-mcp
echo "# MCP Demo" > ~/Documents/demo-mcp/README.md
echo "hello from mcp" > ~/Documents/demo-mcp/notes.txt

在 AgentHub 找 MCP

打开 /mcp，搜索 filesystem 或「文件系统」，进入详情页。下文以带路径参数的典型 filesystem Server 为例；字段名以详情页生成的 JSON 为准。

1. 打开目标 MCP 详情页（本例：filesystem）
2. 找到「快速安装 / Install」区域，选 Cursor Tab
3. 点击 复制

得到类似结构（示意，以页面为准）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents/demo-mcp"
      ]
    }
  }
}

读懂这段配置（字段对照）

无论详情页是 filesystem 还是上图里的 sbuilder-mcp，结构都一样：

关键点

• args 最后一段若是「允许访问的目录」——务必改成你刚创建的 demo-mcp 绝对路径
• macOS / Linux 用 /Users/... 或 /home/...；Windows 按该 MCP 文档写路径
• 若详情页有 env 占位符（API_KEY 等），先填真实值再保存，否则 Server 起不来

项目级（推荐练习）

在你正在打开的项目根目录创建：

mkdir -p .cursor

新建或编辑 .cursor/mcp.json，把上一步的 mcpServers 合并进去。若已有其他 Server，只追加新 key，不要整文件覆盖。

完整最小示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents/demo-mcp"
      ]
    }
  }
}

然后按顺序做：

1. Cmd+Shift+P（Windows：Ctrl+Shift+P）→ Reload Window
2. 打开 Cursor Settings → MCP（或 Features → MCP）
3. 确认 filesystem 为已连接；首次 npx 可能下载几十秒：Starting → Connected

你会看到的界面效果

• 列表里出现名为 filesystem（或你 JSON 里的 key）的条目
• 展开后能看到 Tools：如 list_directory、read_file、write_file
• 若是红 / Error：点开日志——常见是路径写错、Node 不在 PATH、JSON 少逗号

打开 Agent 对话（Composer / Agent 模式，确保能使用工具），依次发送：

提示词 A｜列目录

请使用 filesystem MCP 的 list_directory（或等价工具），列出目录 /Users/你的用户名/Documents/demo-mcp 下的文件，只输出真实工具返回结果，不要猜测。

期望效果 A

• 出现工具调用卡片，参数路径指向 demo-mcp
• 结果中同时出现 README.md 与 notes.txt
• 若只编造文件名、且没有工具调用条 → MCP 未启用或模型没选工具，回到设置检查 Connected

提示词 B｜读文件

继续用 MCP 读取该目录下的 notes.txt 全文，原样引用内容。

期望效果 B

• 再次出现 read_file（或类似）工具调用
• 回复中出现 hello from mcp（你 echo 进去的原文）

提示词 C｜对比「没 MCP」时

1. 关掉该 MCP，或暂时从 mcp.json 删掉后 Reload
2. 再问同样问题：模型往往只能猜路径或说无法访问本地文件
3. 再打开 MCP：又能读到真实内容

这就是 MCP 的价值：工具调用 + 真实结果。

任意 AgentHub 上的 MCP（GitHub、Postgres、Playwright、飞书…）都按同一四步走：

1. 详情页 → Cursor / Claude Code / VS Code Tab → 复制
2. 合并进客户端配置，填 env / 路径 / Token
3. 重载 → 确认 Connected + Tools
4. 用「点名工具能力」的提示词验证

按类型怎么写验证话术

详情页侧栏「客户端接入与实战」也会链回本文，方便随时对照。

Claude Code

1. AgentHub 详情页 → Claude Code Tab → 复制命令
2. 终端执行，例如：

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/你/Documents/demo-mcp

3. 开新会话，用同样的「列目录 / 读 notes.txt」提示词验证
4. 可用 claude mcp list 查看是否已添加

VS Code / Windsurf / Cline 等

以详情页对应 Tab 生成的片段为准；验证标准不变：必须出现工具调用 + 真实数据。

更短的安装说明见：Cursor 安装 MCP、Claude Code 安装 MCP。

做完本实例后，你可以回到任意 MCP 详情页一键复制配置，用同一套标准验收：

1. 看见 工具调用
2. 看见 真实结果