Claude Code MCP 完全指南：添加、配置与管理 MCP 服务器

Claude Code 如何连接 MCP 服务器

Claude Code 通过 claude mcp add 命令连接 MCP 服务器：远程服务器用 --transport http 加上 URL，本地 stdio 服务器则把启动命令写在 -- 之后。每个服务器都保存在三种作用域之一（local、project 或 user），在会话中通过 /mcp 菜单查看状态、登录和重连。

本文会逐一展开上面这段话，所有命令都对照官方 Claude Code MCP 文档核对过。如果你只是想找个服务器先接上，可以先逛逛 MCP 服务器目录。

速查表

第 1 步：选择传输方式

MCP 服务器大体分两类，Claude Code 都支持。

远程 HTTP 服务器（推荐）

大多数托管服务器提供 Streamable HTTP 端点。用 --transport http 传入 URL：

claude mcp add --transport http notion https://mcp.notion.com/mcp

如果服务器用 API Key 而不是 OAuth，就通过请求头传入：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

第二个例子是使用细粒度个人访问令牌的 GitHub MCP 服务器。注意 claude mcp add 保存配置时不会校验凭据，令牌填错只会在之后表现为连接失败。

远程 SSE 服务器（已弃用）

一些较老的服务器仍在使用 Server-Sent Events。SSE 传输在 MCP 规范中已被弃用，但 Claude Code 仍然支持：

claude mcp add --transport sse asana https://mcp.asana.com/sse

按照文档说明，较新版本的 Claude Code 在对只支持 SSE 的端点使用 --transport http 时，也会自动回退到 SSE。

本地 stdio 服务器

stdio 服务器是 Claude Code 在你本机启动的进程，通常通过 npx、uvx 或二进制文件运行。-- 分隔符之后的所有内容都会原样传给服务器：

claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

记住三条规则，就能避开大多数 stdio 配置错误：

• Claude Code 自己的选项（--transport、--env、--scope、--header）要写在 -- 分隔符之前。
• 传给服务器的参数（比如 npx 的 -y 或 --port 8080）要写在 -- 之后。
• --env 可以接收多个 KEY=value。如果服务器名紧跟在 --env 后面，CLI 会把名字当成另一个键值对而报错，所以在两者之间放一个别的选项，比如 --transport stdio。

也有简写：-t 对应 --transport，-e 对应 --env，-H 对应 --header，-s 对应 --scope。

第 2 步：选择作用域

你添加的每个服务器都属于一个作用域，默认是 local。

实践中好用的原则：

• local：个人试验，以及任何带你自己凭据的服务器。
• project：团队成员克隆仓库后都应该拿到的服务器，比如文档服务器，或用于 UI 测试的 Playwright MCP 服务器。
• user：你在哪都想用的工具，比如提供最新库文档的 Context7。

当同名服务器出现在多个作用域时，local 优先于 project，project 优先于 user。最终使用的是胜出作用域里的完整条目，字段不会合并。

第 3 步：用 .mcp.json 共享服务器

用 --scope project 添加服务器后，项目根目录会生成这样一个文件：

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

你也可以手动编辑 .mcp.json 并提交。有两个细节要注意：

• 只写了 url 而没有 type 的条目会被当成 stdio，从而失败。远程服务器一定要写 "type": "http"（或 "sse"）。
• 在交互式会话中，Claude Code 使用项目服务器前会请求你批准，而克隆下来的仓库无法自己批准自己的服务器。批准之前，claude mcp list 会显示该服务器处于待批准状态。想重置批准记录，运行 claude mcp reset-project-choices。

用环境变量把密钥挡在 git 之外

.mcp.json 支持在 command、args、env、url 和 headers 中展开变量：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} 展开为变量的值，${VAR:-default} 在未设置时使用默认值。如果变量未设置又没有默认值，配置里会保留字面文本，claude mcp list 会给出警告。关于如何安全地管理令牌，参见我们的 MCP 安全最佳实践。

第 4 步：用 OAuth 认证

很多托管服务器（Notion、Sentry、Linear 等）用 OAuth 代替静态密钥。先添加服务器，再在 Claude Code 里登录：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

启动 claude，输入 /mcp，选中该服务器，在浏览器中完成登录。也可以在 shell 中用 claude mcp login sentry 登录（无图形界面的机器上加 --no-browser），用 claude mcp logout sentry 清除已保存的令牌。

需要了解的几个限制：

• 非交互式运行（claude -p）无法完成 OAuth。请先在交互式会话中登录一次。
• 需要预先注册 OAuth 应用的服务器，可以在添加时使用 --client-id、--client-secret 和 --callback-port。

这套流程在协议层面的原理，见 MCP 认证与 OAuth。

第 5 步：按照别人的说明添加服务器

很多 README 只给了 Claude Desktop 或 Cursor 的配置。按下面的方式转换：

• 一个 URL 表示远程服务器：claude mcp add --transport http name URL。
• 一条启动命令，比如 npx -y @example/mcp-server，表示 stdio：claude mcp add name -- npx -y @example/mcp-server。
• 一个 mcpServers JSON 块：把里面的对象（而不是外层包装）传给 add-json。

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

add-json 同样支持 --scope user 或 --scope project。

从 Claude Desktop 导入

如果你的服务器已经在 Claude Desktop 里跑通了，直接导入：

claude mcp add-from-claude-desktop

运行后会出现交互式选择界面，让你挑选要导入的服务器。该功能仅支持 macOS 和 WSL。服务器名只能包含字母、数字、连字符和下划线，所以名字里带空格的 Desktop 服务器会被跳过；重名的会加上后缀，比如 server_1。

日常管理

claude mcp list          # 所有服务器及健康状态
claude mcp get notion    # 单个服务器的详情
claude mcp remove notion # 删除它（连同保存的 OAuth 令牌）

在会话中，/mcp 会显示每个服务器的状态和工具，还能重连、重新认证或在不删除的前提下禁用服务器。常见状态包括 ✔ Connected、! Needs authentication、✘ Failed to connect 和 ⏸ Pending approval。

上下文占用与工具搜索

工具搜索默认开启：Claude Code 启动时只加载工具名，等 Claude 需要时再获取完整定义，所以多加几个服务器对上下文窗口影响很小。如果某个小服务器每轮都要用，可以在它的条目上设置 "alwaysLoad": true 让它预先加载。想彻底关闭延迟加载，用 ENABLE_TOOL_SEARCH=false claude 启动。客户端如何发现工具的背景知识，见 MCP 工具发现。

资源与提示词

服务器可以暴露用 @ 引用的资源，例如 @github:issue://123；也可以暴露提示词，它们会以 /mcp__servername__promptname 的形式出现在斜杠命令中。如果不确定一个服务器暴露了什么，参见 MCP 资源与工具的区别。

故障排查

stdio 服务器崩溃时，先在终端里直接运行它的命令测试。远程服务器行为异常时，用 MCP Inspector 看它到底返回了什么。另外注意，stdio 服务器不会自动重连，需要用 /mcp 手动重连。

Claude Code 推荐的 MCP 服务器

浏览器服务器请参考专门的 Playwright MCP Claude Code 配置指南。

下一步

挑一个你这周真的会用到的服务器，先以 local 作用域添加，并在 /mcp 中确认它显示 ✔ Connected，再考虑添加更多。等它证明了价值，再把它移到 project 作用域，让团队也用上。想发现更多服务器，可以浏览 MCP 服务器目录，或按分类筛选。