Claude Code MCP 怎么配置？2026 Claude Code MCP 配置教程（附常用 MCP 服务器）

Claude Code MCP 让 Claude 不只会读写本地代码，还能直接查 GitHub Issue、读 Notion 文档、看 Sentry 报错、查询数据库。配置方法只需要一条 claude mcp add 命令，难点在于选对传输方式和作用范围。

这篇 Claude Code MCP 配置教程会讲清 MCP 是什么、怎么添加和管理 MCP 服务器、.mcp.json 怎么写，并附上常用 MCP 服务器的配置命令。还没安装 Claude Code 的话，先看《Claude Code 教程：2026 Claude Code 安装与使用指南》。

---

MCP 是什么

MCP（Model Context Protocol，模型上下文协议）是一个开源标准，用来把 Claude Code 连接到外部工具、数据库和 API。每个 MCP 服务器向 Claude 提供一组工具，例如"列出 PR""查询表结构""读取页面"，Claude 在需要时自己调用。

接入 MCP 之后，你可以直接这样提需求：

看一下 Sentry 里最近 24 小时最多的报错，找到对应代码并修复，
再到 GitHub 上开一个 PR

---

Claude Code MCP 配置：3 种添加方式

方式一：添加远程 HTTP 服务器（推荐）

远程服务器用 HTTP 传输，这是官方推荐的方式：

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

需要在请求头里带令牌的服务器，加上 --header：

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

SSE 传输（--transport sse）已被官方标记为弃用，服务方提供 HTTP 地址时优先用 HTTP。

方式二：添加本地 stdio 服务器

本地服务器以子进程方式运行，-- 后面的内容是启动命令，--env 用来传环境变量：

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

注意 --env、--transport 等选项要写在服务器名称和 -- 之前。

方式三：用 JSON 一次性添加

已有现成配置时，可以用 claude mcp add-json 直接传入 JSON：

claude mcp add-json my-api '{"type":"http","url":"https://api.example.com/mcp"}'

---

Claude Code MCP 的三种作用范围

作用范围	生效位置	是否共享给团队	存储位置
local（默认）	仅当前项目	否	~/.claude.json
project	仅当前项目	是，通过 Git 共享	项目根目录的 .mcp.json
user	你的所有项目	否	~/.claude.json

添加时用 --scope 指定：

# 团队共享：写入项目的 .mcp.json
claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp

# 个人所有项目可用
claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp

选择建议：团队都要用的服务器（项目的 Sentry、数据库）用 project；带个人令牌的服务器用 local 或 user，避免令牌被提交到仓库。

---

.mcp.json 怎么写

project 作用范围的服务器保存在项目根目录的 .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} 在变量未设置时使用默认值。这样 .mcp.json 可以放心提交到 Git，令牌留在每个人自己的环境变量里。

---

管理和验证 MCP 服务器

claude mcp list            # 查看所有已配置的服务器
claude mcp get notion      # 查看某个服务器的详情
claude mcp remove notion   # 删除服务器

在 Claude Code 会话中输入 /mcp，可以查看每个服务器的连接状态和提供的工具。需要 OAuth 登录的远程服务器（如 Notion、Sentry），在 /mcp 中选择它并按浏览器提示完成授权；在终端里也可以用 claude mcp login <名称>。

在对话中使用 MCP 资源和提示词

• 引用资源：输入 @ 可以看到 MCP 服务器提供的资源，格式为 @server:protocol://resource/path，例如 @github:issue://123。
• 运行 MCP 提示词：输入 / 能看到 MCP 服务器提供的提示词命令，也可以直接输入 /mcp__github__list_prs 这类命令运行。

---

常用 Claude Code MCP 服务器配置命令

以下命令来自官方文档示例，复制后替换令牌即可使用：

用途	配置命令
GitHub：管理 PR、Issue	claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"
Notion：读写文档	claude mcp add --transport http notion https://mcp.notion.com/mcp
Sentry：查看线上报错	claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
PostgreSQL：查询数据库	claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@host:5432/db"
Airtable：读写表格	claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

连接数据库时，建议使用只读账号，避免 Claude 误改生产数据。

---

MCP 会消耗多少 Token

MCP 工具的定义和调用结果都会进入上下文，按 Token 计费。Claude Code 做了两层控制：

1. 工具搜索默认开启：会话开始时只加载工具名称和服务器说明，具体的工具定义在 Claude 需要时才加载，所以多加几个服务器对上下文影响不大。
2. 输出上限：单次 MCP 工具输出超过 1 万 Token 时会提示警告，默认最多返回 2.5 万 Token，可以用环境变量 MAX_MCP_OUTPUT_TOKENS 调整。

即便如此，不用的服务器最好在 /mcp 里停用；gh、aws 这类命令行工具能完成的事，直接让 Claude 用 CLI 通常更省 Token。更多省钱方法见《Claude Code Token 消耗太快？10 个 Claude Code 省 Token 技巧》。

---

Claude Code MCP 安全注意事项

• 只连接你信任的服务器：官方提醒，会抓取外部内容的 MCP 服务器可能带来提示词注入风险。
• 令牌不要写进 .mcp.json：用 ${VAR} 引用环境变量，或用 local / user 作用范围保存个人令牌。
• 最小权限：GitHub 令牌只开需要的权限，数据库用只读账号。
• 团队规范写进 CLAUDE.md：例如"只允许通过 db 服务器执行 SELECT"，写法见《CLAUDE.md 怎么写？Claude Code 项目记忆配置指南》。

通过 API中转站使用 Claude Code 时，MCP 服务器运行在你本地或第三方服务上，与中转站无关，配置方式完全相同。中转站的配置步骤见《Claude API 中转怎么用？国内 Claude Code 中转站配置教程》。

---

常见问题 (FAQ)

Q: Claude Code MCP 配置文件在哪里？

答： local 和 user 作用范围的 MCP 服务器保存在 ~/.claude.json，project 作用范围的服务器保存在项目根目录的 .mcp.json，后者可以提交到 Git 与团队共享。

Q: claude mcp add 的默认作用范围是什么？

答： 默认是 local，只在当前项目对你自己生效；需要团队共享时加 --scope project，需要在所有项目中使用时加 --scope user。

Q: 怎么确认 MCP 服务器连接成功？

答： 在终端运行 claude mcp list 查看已配置的服务器，在 Claude Code 会话中输入 /mcp 查看每个服务器的连接状态和工具列表，需要登录的服务器也在 /mcp 中完成授权。

Q: MCP 的 SSE 和 HTTP 传输有什么区别？

答： 两者都用于远程服务器，但 SSE 传输已被官方标记为弃用，新配置应优先使用 --transport http；本地运行的服务器则使用 stdio 传输。

Q: MCP 服务器多了会不会很费 Token？

答： Claude Code 默认开启工具搜索，启动时只加载工具名称，用到时才加载完整定义，所以影响较小；但工具调用结果仍会占用上下文，不用的服务器建议在 /mcp 中停用。