# Claude Code 怎样添加 MCP 服务器

> 在项目文件夹里运行 `claude mcp add`。写法取决于服务器在哪儿运行：远程服务器写 `--transport http`、一个名称和网址，本地服务器写名称、双短横线，再跟启动它的命令。加完再运行 `claude mcp list`，看它连没连上。

Mindket 编辑部 · 发布于 2026-10-19 · 更新于 2026-11-03 · https://mindket.com/cn/blog/add-mcp-server-claude-code

## 要点

- 本地服务器那一行，服务器名称别紧跟在 `--env` 后面。
- 团队改了 `.mcp.json` 却不见生效，就找找有没有同名的本地作用域条目。
- 请求头里是真密钥时，`claude mcp get` 的输出别贴进问题反馈。
- 登录过的服务器，先运行 `claude mcp logout`，再运行 `claude mcp remove`。

## 四步加上一个服务器

先看服务器的 README。上面给的要么是一个网址，比如 `https://mcp.notion.com/mcp`，要么是一条命令，比如 `npx -y airtable-mcp-server`，由 Claude Code 在你电脑上运行。

> **Anthropic 自己的提醒**
>
> 连接每个服务器之前，先确认你信任它。会抓取外部内容的服务器，可能让你面临提示注入的风险。
>
> Anthropic, Claude Code MCP 文档里的警告框，引文为译文, [Claude Code 文档：通过 MCP 将 Claude Code 连接到工具](https://code.claude.com/docs/en/mcp) (2026-11-03 查阅)

1. 选好服务器，并想清楚它是否可信。连接前该看哪些地方，[《MCP 服务器安全吗》](https://mindket.com/cn/blog/are-mcp-servers-safe)有一份清单。
2. 在要用它的那个项目里打开终端，因为不加 `--scope` 时，服务器归你当前所在的文件夹。然后运行添加命令，Notion 的写法是 `claude mcp add --transport http notion https://mcp.notion.com/mcp`。
3. 运行 `claude mcp list`，看服务器旁边的状态。每种状态在实际运行中是什么意思，见[《服务器连不上时查什么》](#check-and-fix)。
4. 启动 `claude`，输入 `/mcp`。需要登录的服务器，会从这里把你带到浏览器。

## 远程服务器：先选 HTTP，再给密钥或登录，删前先登出

Claude Code 里的 `http`，就是 MCP 官方说的 Streamable HTTP。[Anthropic 的文档](https://code.claude.com/docs/en/mcp)推荐远程服务器用它，更早的 SSE 传输则已经标成弃用。从 v2.1.265 起，服务器不接受 HTTP 时，Claude Code 会自己退回 SSE。

用固定密钥的服务器，把密钥放进 `--header`，加引号，格式照它自己的文档写。用 OAuth 登录的，按第 4 步走，或者在终端里运行 `claude mcp login notion`。

`claude mcp remove` 只删掉 Claude Code 在本机存的 OAuth 令牌，签发令牌的授权服务器那边并不会吊销。那边支持吊销的话，`claude mcp logout notion` 会去吊销，会话里 `/mcp` 菜单中的 Clear authentication 也一样。对一个从没登录过的服务器，`logout` 只会打印一句 `Signed out of "notion"`。

````bash
# A remote server over HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A server that takes a fixed key in a header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

````

**服务器连上来的三种方式**

| | 远程 HTTP | 远程 SSE | 本地 stdio |
| --- | --- | --- | --- |
| 在你的电脑上运行 | ✗ 否 | ✗ 否 | ✓ 是 |
| Anthropic 的文档里标为已弃用 | ✗ 否 | ✓ 是 | ✗ 否 |
| 命令里名称后面跟什么 | 网址 | 网址 | 双短横线，再接启动命令 |

来源：[Claude Code 文档：MCP](https://code.claude.com/docs/en/mcp) (2026-11-03 查阅)

[![Anthropic 在 X 上的帖子：Claude Code 现在可以连接远程 MCP 服务器，把你工具里的上下文直接带进 Claude Code，不需要本地配置，发布于 2025 年 6 月 18 日](https://mindket.com/blog/shots/x-anthropicai-remote-mcp.webp?v=d8f1269cdf48)](https://x.com/AnthropicAI/status/1935367951542280239)

Anthropic 在 X 上，2025 年 6 月 18 日

> X 官方嵌入卡片的截图，11 月 3 日拍摄，时间为美国太平洋时间。帖子里的视频没有收入。点击截图可到 X 上打开原帖。

## 本地服务器和那个双短横线

本地服务器由 Claude Code 自己启动，双方通过标准输入和标准输出通信，也就是[《什么是 MCP》](https://mindket.com/cn/blog/what-is-mcp)里讲的 `stdio` 传输。你敲的这一行以 `--` 为界分成两半。前半截的选项，比如 `--transport`、`--env` 和 `--scope`，归 Claude Code。后半截原样交给服务器，所以服务器自己的参数，比如 `--port 8080`，要放在最后。

服务器名称要是紧跟在 `--env` 后面，命令会当场报错：`Invalid environment variable format: airtable`。原因是 `--env` 能接好几组 `KEY=value`，名称就被当成了又一组变量。办法是在两者之间隔一个别的选项，比如文档里的 `--transport stdio`，或者照 `claude mcp add --help` 的例子，名称写在前，`-e` 写在后。

有的 README 给的是一段 JSON 而不是命令，这时用 `claude mcp add-json` 原样收下。要传的是 `mcpServers` 里面那个对象，外面那层不要。

````bash
# Claude Code's options, then --, then the server's own command
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# The same, name first, the way claude mcp add --help writes it
claude mcp add airtable -e AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server

# A server whose README gives JSON instead of a command
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

````

## 本地、项目还是用户：三种作用域各存在哪里

默认的作用域叫“本地”，这个名字容易误导人。这样加的服务器存在你主目录下的 `~/.claude.json` 里，按项目路径归档，并不在项目自己的 `.claude/settings.local.json` 里。只有你自己、只在一个项目里用的服务器，放这里正合适。想在所有项目里都用，就放用户作用域。

要让整个团队都用上同一个服务器，就加在项目作用域。它会在项目根目录写一个 `.mcp.json`，配置跟着仓库走，谁也不用再抄一遍命令。我们用这种方式加 Notion，生成的文件里只有 `"type": "http"` 和网址。

在交互式会话里，Claude Code 用这个文件里的服务器之前会先问你，因为克隆下来的仓库可能自带 `.mcp.json`。想清掉以前的选择，运行 `claude mcp reset-project-choices`。密钥别写进要提交的文件：`.mcp.json` 会从环境变量展开 `${API_KEY}`，也可以在 `:-` 后面写一个默认值。变量没设置、也没有默认值的，会按字面原样加载，`claude mcp list` 会给出警告。

同一个名称在两个作用域里都有，Claude Code 也只建一个连接，用的是排位更高那个作用域里的完整定义，两边的字段不会拼在一起。所以一条旧的本地条目，会把团队后来改过的项目条目整个盖住。

**同名服务器出现两次，谁说了算**

1. 本地作用域。只属于你、只在这个项目里生效的条目，存在 `~/.claude.json`。
2. 项目作用域。团队提交到仓库的 `.mcp.json`。
3. 用户作用域。对你所有项目都生效的条目。
4. 插件提供的服务器。已安装的插件自带的服务器。
5. claude.ai 连接器。你 claude.ai 账户里的连接器，排在最后。

来源：[Claude Code 文档：MCP](https://code.claude.com/docs/en/mcp) (2026-11-03 查阅)

| 作用域 | 在哪里加载 | 是否与团队共享 | 存放位置 |
| --- | --- | --- | --- |
| 本地（默认） | 当前项目 | 否 | `~/.claude.json` |
| 项目 | 当前项目 | 是，通过版本控制 | 项目根目录的 `.mcp.json` |
| 用户 | 你的所有项目 | 否 | `~/.claude.json` |

## 服务器连不上时查什么

下面的输出来自 Windows 11 上的 Claude Code 2.1.314，运行于 2026 年 11 月 3 日。我们往一个空文件夹里加了四个服务器。Notion 的远程服务器加了两次，第二次加在项目作用域下。另外两个是故意配错的：一个连 `api.example.com`，密钥是编出来的，另一个本地服务器指向一个不存在的文件。事后四个都删掉了。

`claude mcp add` 对每一个都打印了成功。编出来的令牌也照样存下，显示成 `[REDACTED]`，地址一次也没试过。`claude mcp list` 这次花了五秒左右，它还会检查你账户里的 claude.ai 连接器，所以会多出几行你没加过的。

`claude mcp get` 把 add 没显示的东西都列了出来：请求头连同令牌，全是明文。

````text
$ claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server
Invalid environment variable format: airtable, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

$ claude mcp list
Checking MCP server health…

notion-team: https://mcp.notion.com/mcp (HTTP) - ⏸ Pending approval (run `claude` to approve)
notion: https://mcp.notion.com/mcp (HTTP) - ! Needs authentication
secure-api: https://api.example.com/mcp (HTTP) - ✘ Failed to connect — ENOTFOUND: getaddrinfo ENOTFOUND api.example.com
broken: node no-such-server.js - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed

$ claude mcp get secure-api
secure-api:
  Scope: Local config (private to you in this project)
  Status: ✘ Failed to connect
  Issue: ENOTFOUND: getaddrinfo ENOTFOUND api.example.com
  Type: http
  URL: https://api.example.com/mcp
  Headers:
    Authorization: Bearer your-token

````

- `! Needs authentication`：服务器有回应，在等你登录，Notion 刚加完时就是这个状态。按第 4 步登录即可。
- `⏸ Pending approval`：项目里的服务器还没人批准。在那个文件夹里启动 `claude`，批准即可。
- `✘ Failed to connect` 加 `ENOTFOUND`：地址解析不了。检查网址有没有拼错。
- `✘ Failed to connect` 加 `CONNECTION_CLOSED`：本地服务器自己退出了。提示里不说原因，把 `--` 后面那段命令拿到终端里单独跑一遍，看它自己报什么错。

> 除了这次运行，文中其他内容都来自 Anthropic 的 Claude Code 文档和 MCP 官方页面，阅读日期见文末来源。

## 常见问题

### 能把 Claude Desktop 里配好的 MCP 服务器导入进来吗？

只有 macOS 和 WSL 支持，命令是 `claude mcp add-from-claude-desktop`，它会读取 Claude Desktop 的配置文件，让你挑要导入哪些服务器。名称里有空格，或有字母、数字、连字符和下划线以外字符的，会被跳过。

### Claude Code 会不经询问就加载项目里的 .mcp.json 吗？

在脚本里会。用 `claude -p` 运行，或在 Agent SDK 会话里，没人能回答批准提示，所以项目作用域的服务器会直接加载。启动时加 `--strict-mcp-config` 能把它们挡在外面，把服务器写进 `disabledMcpjsonServers` 也行。

### 服务器启动慢，怎样多给它一点时间？

用环境变量 `MCP_TIMEOUT`，单位是毫秒，比如 `MCP_TIMEOUT=10000 claude`，服务器就有十秒钟可以启动。工具调用的超时是另一个变量，叫 `MCP_TOOL_TIMEOUT`。

### MCP 服务器加多了，会把上下文窗口占满吗？

会话开始时只加载工具名称和服务器说明，完整的工具定义等 Claude 用到时才加载，这个机制叫工具搜索。所以多加一个服务器，开头占的地方很少。Claude Code 也没给每个服务器的工具数设固定上限，不过工具定义一旦加载，就会占掉一部分上下文窗口。

### Claude Code 自己能当 MCP 服务器吗？

`claude mcp serve` 会把 Claude Code 作为 stdio 服务器运行，Claude Desktop 通过配置文件就能连上来，开放的只有 Claude Code 自己的工具。终端里静悄悄的是正常现象，那是服务器在等客户端。

## 资料来源

- [Claude Code 文档：通过 MCP 将 Claude Code 连接到工具](https://code.claude.com/docs/en/mcp) (2026-11-03 查阅)
- [Claude Code 文档：创建插件](https://code.claude.com/docs/en/plugins/create) (2026-11-02 查阅)
- [Model Context Protocol：架构概览](https://modelcontextprotocol.io/docs/learn/architecture) (2026-11-02 查阅)
- [Model Context Protocol：MCP 是什么？](https://modelcontextprotocol.io/docs/getting-started/intro) (2026-11-02 查阅)

[浏览 MCP 服务器](https://mindket.com/cn/mcp-servers)