Claude Code 开箱就会读写文件、跑 shell 命令，但它默认是个孤岛：摸不到你的数据库、开不了浏览器、看不见 issue 系统里的工单。MCP（Model Context Protocol）是 Anthropic 于 2024 年 11 月开源的开放协议，用 JSON-RPC 2.0 把工具与数据源标准化成一个个”服务器”，任何客户端都能接，OpenAI 与 Google 随后相继宣布支持，现在是编码代理接外部能力的事实标准。这篇手把手装好第一个 MCP 服务器，并避开 Windows、scope、授权这三个最常见的坑。
解决什么问题
没有 MCP 时，想让 Claude Code 查一个线上接口返回什么、看一眼页面渲染对不对，你只能自己跑命令、把输出粘给它。装上对应的 MCP 服务器后，这些动作变成它能直接调用的工具：查数据库、开真浏览器点页面、拉 issue 进上下文，都是一句话的事。
对 Claude Code 来说，MCP 是它从”本地文件助手”变成”能伸手的代理”的那只手。这篇教程结束时，你会装好一个本地服务器、一个远程服务器，搞懂三种配置范围的区别，并且知道五个最常见的坑分别长什么样。
环境与版本
- Claude Code：npm 包 @anthropic-ai/claude-code，要求 Node.js 18+。终端跑
claude --version确认可用（写稿时的版本号【待补：claude —version 输出】）。 claude mcp子命令组在 2.0 之前的版本就已存在，本文步骤按 2.x 命令行整理；写稿时的默认主力模型是 Sonnet 系列（Sonnet 4.5 一代起，当前默认【待补】），公开规格 20 万 token 上下文窗口——MCP 服务器的工具定义和调用回显都会吃这个窗口，服务器不是装得越多越好。- Windows 用户建议在 WSL 或 Git Bash 里操作；Windows 原生 CMD / PowerShell 有一个 npx 包装坑，见常见坑第 1 条。
分步配置
第 1 步：确认 CLI 可用
claude --version
claude mcp --helpclaude mcp --help 会列出 add、list、get、remove 四个高频子命令，后面的所有操作都靠它们，不需要手动编辑配置文件也能完成大部分事情。
第 2 步：装第一个本地（stdio）服务器
以官方维护的 filesystem 服务器为例，让 Claude Code 能在指定目录里自由读写：
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects三个细节：-- 之后是服务器的启动命令；这类以子进程方式常驻的叫 stdio 传输，Claude Code 通过标准输入输出跟它通信；-y 让 npx 免确认拉包，末尾的目录是授权范围，宁可给窄、用着再放。
验证是否装上了：
claude mcp list
claude mcp get filesystem第 3 步：搞懂 scope——local、project、user
scope 决定配置存在哪、跟着谁走，新手最懵的就是它：
- local（默认）：存在本机当前项目下，换个目录就”消失”。
- project：写进项目根目录的 .mcp.json，随 git 提交，全组共享。
claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem .- user：跟着你的账号走，适合装个人常用集，比如浏览器自动化：
claude mcp add --scope user playwright -- npx -y @playwright/mcpproject scope 生成的 .mcp.json 长这样，支持 ${VAR} 形式引用环境变量，token 一律走环境变量，不要硬编码进仓库：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
},
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp"]
}
}
}第 4 步：接一个远程（HTTP）服务器
远程服务器不由本机拉起子进程，直接访问一个 URL，例如公共的 deepwiki 服务：
claude mcp add --transport http deepwiki https://mcp.deepwiki.com/mcp端点 URL 以各服务器官方文档为准【待补：发稿前逐个复核】。需要 OAuth 登录的远程服务器，在会话里输入 /mcp 打开面板完成授权（流程截图【待补】）。
第 5 步：会话内验证与授权收紧
启动 claude 进入会话，输入 /mcp：能看到每个服务器的连接状态与工具列表，工具名格式为 mcp__服务器名__工具名。MCP 工具默认逐次询问授权，常用的可以写进项目里的 .claude/settings.json 允许清单：
{
"permissions": {
"allow": ["mcp__deepwiki"]
}
}mcp__deepwiki 放行该服务器的全部工具；写具体工具名（形如 mcp__deepwiki__ask_deepwiki）则只放行单个，颗粒度自己权衡。
常见坑（全部真实存在）
坑一：Windows 原生环境 npx 直启失败
Windows（非 WSL）下 npx 不是可执行文件而是 cmd 脚本，直接当命令启动会报连接失败或启动超时。解法是套一层 cmd /c，这也是官方文档明确写出的 Windows 差异：
claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem D:\code（当前版本下的复验截图【待补】。）
坑二：scope 装错，服务器”时有时无”
local scope 绑定当前目录，换目录或换机器配置就不在了，症状是”昨天还好好的今天没了”。解法：个人常用工具用 --scope user 装；团队共享的用 --scope project 落进 .mcp.json 提交到仓库。装错就用 claude mcp remove 名字 删掉重装到正确 scope。
坑三：.mcp.json 首次使用要人工批准
clone 别人的仓库后，项目级服务器不会静默生效——Claude Code 会提示你审查并批准，这是防供应链投毒的安全设计。别闭眼点同意，先看配置里写了什么命令、什么参数，再决定批不批。
坑四：stdio 服务器把日志打到 stdout 会握手失败
MCP 用 stdout 传协议消息，服务器日志混进去就是乱码和连接失败。自己写 MCP 服务器时，日志一律走 stderr；排查这类问题时，先怀疑最近有没有往 stdout 打印东西。
坑五：工具装太多，上下文被吃光
每个服务器的工具定义都会进入模型上下文，20 万 token 的窗口经不起无节制堆服务器，表现为响应变慢、模型”变笨”。按项目精简启用，不常用的 claude mcp remove 掉。
最终效果
全部配好后：claude mcp list 里各服务器显示已连接，会话内 /mcp 面板绿灯（截图【待补】）。实际体感是这样的——让 Claude Code”用 deepwiki 查 react-router 的 loader 用法，把要点写进 docs/router-notes.md”，它会自己调用 deepwiki 的工具拉取资料，再落盘写文件：工具侧是 MCP 伸出去的手，思考侧靠 Sonnet 系列模型 20 万 token 的上下文消化工具回显。
连接不上时按这个顺序排查：claude mcp list 看状态 → 会话内 /mcp 面板看错误详情 → 超时类问题调 MCP_TIMEOUT / MCP_TOOL_TIMEOUT 环境变量（默认值【待补：官方文档】）→ 最后回看 scope 和 Windows 包装这两个高频坑，大多数”配了没用”都栽在这两处。