Claude Code MCP 服务器配置教程：从零接上你的第一个工具

本文面向使用 Claude Code CLI 的开发者。文中命令与配置文件字段以 Claude Code 官方文档为准（as-of 2026-10-10）；MCP 生态迭代较快，动手前请对照 Anthropic 官方 Claude Code MCP 文档确认当前写法。

Claude Code 内置了读文件、跑命令、改代码的能力，但一旦你需要它去查数据库、调内部 API、读浏览器里的页面，内置工具就不够用了。MCP（Model Context Protocol） 就是补上这一块的扩展协议：它把外部能力包装成一组工具，让 Claude Code 像调用自带工具一样调用它们。本文用一条主线讲清「MCP 是什么 → 配置前准备 → 三步接上一个 server → 排错 → 用统一网关收口 key」，让你第一次配置就成功。如果你还没装 Claude Code，可以先看 Claude Code 从零开始教程。

一、MCP 是什么：Claude Code 的外接工具层

MCP 是 Anthropic 提出的开放协议，用来描述「一个程序能给模型提供哪些工具、哪些资源」。一个 MCP server 是一个独立进程或服务，它对外声明若干工具（tools）、资源（resources）和提示模板（prompts）；Claude Code 作为 MCP client 连接它，把声明的工具并入自己的可用工具集。

对你的日常使用而言，理解三点就够了：

传输方式：本地进程用 stdio（Claude Code 负责拉起子进程并通过标准输入输出通信），远程服务用 HTTP / SSE。
作用域：配置可以只在当前项目生效（project）、只对你本机生效（local），或对所有项目生效（user）。团队共享的配置建议走 project 作用域并提交进仓库。
一次配置，长期可用：server 一旦注册成功，之后每次启动 Claude Code 都会自动挂载，不需要重复配置。

二、配置前的准备

动手前确认三件事：

Claude Code 已安装且能正常启动（claude --version 有输出）。
Node.js 18+ 与 `npx` 可用——绝大多数社区 MCP server 以 npm 包分发，npx 是最省事的启动方式，无需全局安装。
明确你要接的能力：读本地目录、连数据库、调某个 SaaS API，还是接入你自己的内部服务。先想清楚目标，再去找对应的 server，比装一堆用不上的强。

安全提醒：MCP server 拥有你赋予它的权限，尤其是文件系统类 server。只安装来源可信的 server，路径参数尽量收窄到具体目录，不要一上来就把整个磁盘根目录交给它。

三、三步接上你的第一个 MCP server

下面以官方的文件系统 server 为例，全程只需一条命令加一次验证。

第一步：注册 server

Claude Code 提供了 claude mcp add 子命令，直接注册即可：

bash

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

-- 之后的整串是 server 的启动命令，Claude Code 会用 stdio 拉起它。想控制作用域时加 --scope：

bash

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

--scope local（默认）：只写进本机当前项目的私有配置，不进仓库。
--scope project：写进项目根的 .mcp.json，可以提交进版本库，团队成员克隆后自动获得同一套配置。
--scope user：对你所有项目生效。

如果你不想用命令行，也可以直接编辑配置文件：project 作用域改项目根的 .mcp.json，user / local 作用域改用户级配置。手写时字段结构很简单——一个 mcpServers 对象，键是 server 名，值是 command / args /（可选的）env：

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    }
  }
}

第二步：验证注册结果

bash

claude mcp list        # 列出已注册的 server 及其连接状态

在交互式会话里，输入 /mcp 也能查看当前挂载的 server 与工具清单。列表里出现你的 server 且状态为正常，就说明注册成功。

第三步：在会话里实际调用一次

启动 Claude Code，直接说「用 filesystem 工具列出项目根目录的文件」。如果 Claude Code 能列出文件，说明整条链路（注册 → 拉起进程 → 工具调用）已经打通。第一次成功调用最好落在真实任务上，比如「帮我读一下 package.json 的依赖版本」，这样你顺手就把配置和实际收益一次验证了。

连接远程 MCP 服务（HTTP / SSE 传输）时，命令换成 claude mcp add --transport http <名字> <URL>，并在需要时通过 --header 传入鉴权头。凭据务必用环境变量或命令行参数注入，不要写进提交进仓库的 `.mcp.json`。

四、常见问题与排错

注册成功但调用失败、工具列表为空？ 九成是 server 进程没起来。手动在终端跑一遍 -- 之后的启动命令，看它能否正常输出——常见原因是包名写错、npx 首次下载超时，或运行环境缺依赖。把命令原样在终端跑通，再回到 claude mcp add 就稳了。

提示找不到命令（command not found）？ Claude Code 拉起子进程时的 PATH 可能和你交互式 shell 不同。最稳妥的写法是用绝对路径的 node / npx，或者在配置里用 env 显式补上需要的环境变量。

server 报权限错误？ 文件系统类 server 的参数决定了它能摸到哪些目录，把路径收窄到项目目录即可；数据库类 server 则检查连接串与只读账号是否配好。遇到 Claude Code 弹出工具授权确认时，先看清是哪个工具、要动什么，再决定是否放行。

多个项目配置冲突？ 记住作用域优先级：local > project > user。同一个名字在不同作用域重复注册时，更具体的作用域会覆盖更宽泛的。排查时先用 claude mcp list 看清当前生效的是哪一份。

五、把 key 收口：让 MCP 与模型走同一个网关

聊到配置，绕不开一个现实问题：很多 MCP server 需要绑定第三方账号或信用卡，而模型调用本身也各自要一套 key。项目里跑两三个 server、再叠上多模型，key 就散落各处，账单也拼不成一张。

如果你不想为每个上游单独申请官方 key、也不想绑外卡，可以直接在 CodeGateway 拿一个 Key：它是多模型 AI Gateway，用一个 Key 统一调用 Claude / GPT / Gemini 等上游模型，账单与配额在一处集中管理，MCP 侧需要的模型调用也能收到同一个出口上。拿 Key 只需两步：登录 CodeGateway Dashboard → 创建 API Key（明文只显示一次，记得当即保存）。想先算成本，定价页有完整价目；想确认模型可用性，模型目录按模型列好了上下文与能力。

小结

配置 MCP 服务器的核心就三件事：用 `claude mcp add` 注册、用 `claude mcp list` 验证、在真实任务里跑通第一次调用。作用域决定配置写在哪、要不要进仓库，stdio 与 HTTP 决定 server 怎么被拉起。排错时，永远先把启动命令在终端单独跑通，再回来看配置。把这一步走顺，Claude Code 就从「会改代码的助手」变成了「能接你整套工具链的协作者」。

Claude Code MCP 服务器配置教程：从零接上你的第一个工具