网上 MCP 的教程要么停在"概念科普"，要么贴个英文官方文档让你自己啃，跟着做总在第二步——加完服务器一运行就报 failed to connect。

本文基于 2026 年 6 月的 Claude Code 最新版实测，从 0 到跑通，每个 MCP 工具都给出可直接复制的配置和验证命令，踩过的坑都标了出来。照着做一遍，你的 AI 编程助手就能读文件、查 GitHub、跑浏览器、查最新文档——建议先收藏，下次重装环境直接照抄。

一、先搞懂：MCP 到底解决什么问题

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 在 2024 年底开源的一套标准。一句话说清它的价值：

它让 Claude 不再是一个"只会聊天的大脑"，而是能调用外部工具的"长了手脚的助手"。

裸用 Claude Code 时，它只能看到你当前对话里贴进去的内容。接上 MCP 之后，它能主动去读你的本地文件、查 GitHub 的 issue、操作浏览器截图、检索某个库的最新官方文档——这些动作不用你再手动复制粘贴。

MCP 的架构只有三个角色，记住就够用：

• MCP 客户端：这里就是 Claude Code 本身。
• MCP 服务器：每个工具是一个独立的小服务（文件系统、GitHub、浏览器……）。
• 传输方式：本地工具走 stdio（标准输入输出），远程工具走 http/sse。

你要做的，就是告诉 Claude Code"去连哪几个服务器"。

二、准备工作（3 分钟）

1. 安装 Claude Code（已装可跳过）：

npm install -g @anthropic-ai/claude-code

2. 确认版本与登录：

claude --version
claude   # 首次会引导登录 Anthropic 账号

3. 本地准备好 Node.js 18+（大多数 MCP 服务器用 npx 拉起，依赖 Node）。验证：

node -v   # 应 >= 18

踩坑 1：很多人 failed to connect 的真正原因是 npx 不在 PATH 里，或公司网络拉不到 npm 包。先单独跑一次 npx -y @modelcontextprotocol/server-filesystem --help，能打印帮助再往下走。

三、Claude Code 加 MCP 的两种方式

方式 A：命令行一条命令加（推荐新手）

# 语法：claude mcp add <名字> -- <启动命令>
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /your/project/path

加完用这条命令检查是否连上：

claude mcp list

看到对应名字后面是 ✓ connected 就成了。

方式 B：项目级配置文件 .mcp.json（推荐团队协作）

在项目根目录建 .mcp.json，团队成员 clone 下来就共享同一套工具：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

两种方式等价，命令行加的会写进用户级配置，.mcp.json 是项目级、可提交到 Git。团队项目优先用 B，避免每人手动配一遍。

四、5 个神级 MCP 工具（照抄即用）

下面每个都给出加法 + 它能干什么 + 一句验证话术。

1. Filesystem —— 让 Claude 直接读写你的项目

最基础也最高频。装上之后，"帮我看看 src 下哪些文件超过 300 行"这种话它能自己去翻。

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ./

验证：在 Claude Code 里问"列出当前目录的所有 markdown 文件"，它会真的去读目录而不是瞎编。

踩坑 2：路径要给到你允许它访问的根目录。给 / 是危险的，给到具体项目目录最稳。

2. GitHub —— 查 issue、读 PR、提交不用切窗口

claude mcp add github -- npx -y @modelcontextprotocol/server-github

需要配一个 GitHub Personal Access Token（在 GitHub Settings → Developer settings 里建），通过环境变量传：

# Windows PowerShell
$env:GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxx"
# macOS / Linux
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxx"

验证：问"看看这个仓库最近 5 个 open 的 issue"，它能直接拉回来。

3. Fetch —— 让 Claude 抓取并读懂任意网页

claude mcp add fetch -- npx -y @modelcontextprotocol/server-fetch

适合"把这个文档页的内容总结成要点"。它会把网页转成干净的 markdown 再读，比你复制粘贴省事得多。

4. Playwright —— 让 Claude 真正操作浏览器

这是质变级的一个。装上后 Claude 能打开页面、点击、填表单、截图——做端到端测试或抓动态页面神器。

claude mcp add playwright -- npx -y @playwright/mcp@latest

验证：问"打开 example.com 并截图"，它会真的跑起一个浏览器。

踩坑 3：首次运行会下载 Chromium，国内网络可能慢。提前跑 npx playwright install chromium 预热。

5. Sequential Thinking —— 给 Claude 装上"分步推理"外脑

复杂任务容易跑偏？这个工具强制 Claude 把问题拆成有序步骤、可回溯地推进，明显降低"想一半忘了前提"的概率。

claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

适合重构、排查疑难 bug 这类需要长链路思考的场景。

五、配好之后怎么验证全链路

一条命令看全部状态：

claude mcp list

逐个确认是 connected。如果某个是 failed：

1. 单独在终端跑它的启动命令（去掉 claude mcp add 前缀那段），看真实报错；
2. 90% 是网络拉包失败或 token 没配；
3. 改完用 claude mcp remove <名字> 删掉重加。

六、避坑清单（实测总结）

现象	真正原因	解决
failed to connect	npx 拉包失败	先手动跑一次启动命令
GitHub 工具 401	token 没注入或过期	重设环境变量再重启 Claude Code
Playwright 卡住	Chromium 没下载完	预跑 playwright install chromium
团队成员配置不一致	用了用户级配置	改用项目级 .mcp.json 提交到 Git
改了配置不生效	Claude Code 没重启	退出重进，配置在启动时加载

写在最后

MCP 不是花架子，它是把 Claude Code 从"聊天框"升级成"能干活的工程助手"的关键一步。上面 5 个工具是我实测下来性价比最高的组合，配置全都给齐了。

• 建议收藏：下次换电脑、重装环境，这份配置直接照抄，不用再翻英文文档。
• 这只是 MCP 实战的第一篇，下一篇我会讲怎么自己写一个 MCP 服务器，把公司内部的接口接进 Claude Code——关注我，第一时间看到。
• 配置过程中卡在哪一步，欢迎在评论区贴出 claude mcp list 的报错，我看到都会回。

把 AI 编程助手的"手脚"接上，效率才真正翻倍。