Claude学院

Claude Code 配置 MCP 服务器完整步骤

在 Claude Code 里配置 MCP 服务器，核心就是三步：用 claude mcp add 注册一个服务器、指定它的传输方式（stdio / SSE / HTTP）、再用 claude mcp list 确认连接成功。下面把每一步、每个参数和常见坑都讲清楚，命令均为 2026 年当前 Claude Code 版本的真实用法。

前置条件

开始前确认以下几点：

第一步：用 claude mcp add 注册服务器

Claude Code 提供了专门的 claude mcp 子命令来管理 MCP 服务器，不需要手写配置文件。最常用的是添加一个 stdio（标准输入输出）类型的本地服务器，语法是：

claude mcp add <名称> [选项] -- <启动命令> [命令参数...]

注意 -- 分隔符：它前面是给 Claude Code 的选项，后面是真正用来启动服务器进程的命令。例如添加官方文件系统服务器：

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/project

添加完成后，输入 claude 进入会话，Claude 就能调用这个服务器暴露的工具（读写文件、列目录等）。

第二步：选择正确的传输方式

MCP 支持三种传输方式，用 --transport（简写 -t）指定，默认是 stdio。

传输方式适用场景添加方式
stdio本地子进程，最常见claude mcp add 名称 -- 启动命令
sse远程服务器，基于 SSE 长连接claude mcp add --transport sse 名称 https://例子.com/sse
http远程服务器，Streamable HTTP（新标准，推荐）claude mcp add --transport http 名称 https://例子.com/mcp

远程服务器如果需要鉴权，用 --header 传请求头，可重复多次：

claude mcp add --transport http github https://api.githubcopilot.com/mcp \
  --header "Authorization: Bearer ${GITHUB_TOKEN}"

GitHub 的连接还有更细致的玩法，参考 Claude 连接 GitHub 的 MCP 配置实战。

第三步：确认连接并管理服务器

常用管理命令一览：

  • claude mcp list —— 列出所有已配置服务器及连接状态（✓ 表示连接成功）。
  • claude mcp get <名称> —— 查看某个服务器的详细配置。
  • claude mcp remove <名称> —— 删除服务器。

也可以在会话内输入斜杠命令 /mcp，实时查看各服务器状态、可用工具，以及对需要 OAuth 的远程服务器发起授权。更多斜杠命令见 Claude Code 常用命令大全。

配置作用域：选对 -s 参数

添加服务器时用 --scope（简写 -s）决定配置写到哪里，这是最容易混淆的一点：

  • local（默认）：只对当前项目、当前用户生效，存在用户级配置里，不会提交到仓库。适合放私人凭证。
  • project：写入项目根目录的 .mcp.json，会随 Git 提交，团队共享。
  • user：对你所有项目生效，跨项目复用。

例如把文件系统服务器加到团队共享配置：

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

手写 .mcp.json（团队协作推荐）

project 作用域生成的 .mcp.json 结构清晰，也可以直接手写。一个同时包含本地与远程服务器的例子：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

这里有两个关键点：一是 env 字段可以注入环境变量给子进程；二是 ${VAR} 这种插值会读取你 shell 的环境变量，所以敏感信息不要硬编码，写成变量引用即可。数据库类服务器的完整配置可参考 Claude 连接数据库实现自然语言查询。

想自己写一个 MCP 服务器

如果现成的服务器不够用，可以自建。MCP 是开放协议，用 Python 或 Node 都能实现一个暴露自定义工具的服务器，然后用上面的 claude mcp add 接进来。从零开发的完整步骤见 MCP Server 怎么搭建？Python 从零开发。MCP 的工具调用机制和 Messages API 里的 Tool Use 同源，理解后者有助于理解前者，可对照 Claude Tool Use 工具调用完整代码实战。

常见问题

claude mcp list 显示服务器连接失败（failed）怎么办？

按顺序排查：1）手动跑一遍 -- 后面的启动命令，看进程能否独立启动；2）确认 npx/uvx 在 PATH 中，Windows 上路径问题尤其常见；3）检查 env 里引用的环境变量是否真的存在；4）远程服务器确认 URL 和鉴权头正确，必要时用 /mcp 重新授权。更系统的排错见 Claude Code 报错排查清单。

配置了服务器但 Claude 不调用它的工具？

先用 /mcp 确认工具已加载、状态为已连接。然后在提问时明确告诉 Claude 你希望它使用某个工具（比如"用文件系统工具读取 config.json"）。也可以在 CLAUDE.md 配置文件 里写明何时该用哪个 MCP 工具，引导模型主动调用。

MCP 服务器是按 Token 计费的吗？

MCP 服务器本身（如文件系统、数据库连接器）运行在你本地或你自己的服务器上，不产生 Anthropic 费用。但服务器返回的内容会作为上下文进入对话，从而消耗 Claude 的输入 Token。具体计费方式以 Anthropic 官网为准，省 Token 的技巧可参考 降低 Token 成本的 5 个方法。

← Claude Code