Claude Code MCP：如何添加服务器，配置存在哪里

如何为 Claude Code 添加 MCP 服务器

1. 选择传输方式

   远程、云端托管的服务器用 HTTP；这是推荐的传输方式，如果服务器只提供已弃用的 SSE 传输，Claude Code 会退回使用 SSE。以本地进程运行的服务器用 stdio。对于 stdio，-- 之后的所有内容都会原样传给服务器。

   # Remote HTTP server (recommended for cloud services)
   claude mcp add --transport http notion https://mcp.notion.com/mcp
   
   # With a bearer token
   claude mcp add --transport http secure-api https://api.example.com/mcp \
     --header "Authorization: Bearer your-token"
   
   # Local stdio server: everything after -- is the server's own command
   claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
     -- npx -y airtable-mcp-server

2. 选择作用域

   不加 --scope 时，服务器的作用域是 local：只有你、只在当前项目。加上 --scope project 会把它写进 .mcp.json 供团队共用，加上 --scope user 则对你的所有项目生效。详见下表。

3. 需要时登录

   很多远程服务器使用 OAuth。在 Claude Code 里运行 /mcp 并选择要认证的服务器，或者在 shell 里运行 claude mcp login <name>。无头模式的 -p 运行无法打开登录流程，所以要先以交互方式登录。

4. 确认已连接

   运行 /mcp 查看每个服务器的状态和工具，或在 shell 里运行 claude mcp list。然后让 Claude 按名字使用这个工具。

5. 管理你的服务器

   在命令行里列出、查看、删除或导入服务器。不常用的服务器可以在 /mcp 里禁用，不必删除。

   claude mcp list            # every configured server
   claude mcp get notion      # one server's details
   claude mcp remove notion   # remove it (run claude mcp logout notion first to revoke tokens)
   claude mcp add-from-claude-desktop   # import from Claude Desktop (macOS, WSL)

来源：Claude Code 文档，Connect Claude Code to tools via MCP

MCP 作用域与配置文件位置

Claude Code 把 MCP 配置存放在以下位置。注意，MCP 的 local 作用域存在 ~/.claude.json 里，而不是 .claude/settings.local.json。

用 .mcp.json 共享服务器

.mcp.json 让整个团队使用同一组服务器。用环境变量把密钥挡在文件之外：${VAR} 会展开为变量的值，${VAR:-default} 在变量未设置时使用默认值。展开在 command、args、env、url 和 headers 中都有效。

1. 引用变量，而不是写入密钥

   每个人第一次使用 .mcp.json 里的项目服务器时，Claude Code 都会请他确认；claude mcp reset-project-choices 可以重置这些选择。带 url 的 JSON 条目还必须有 type，比如 http。

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

优先级、连接器及其他细节

• 同一个服务器被定义两次时，Claude Code 只连接一次，按以下顺序取第一个：local、project、user、插件、claude.ai 连接器。条目不会合并；组织的托管服务器优先级高于以上所有。
• 如果你用 claude.ai 账号登录 Claude Code，你在 claude.ai 里添加的连接器会自动出现。
• Claude Code 本身也可以作为 MCP 服务器：claude mcp serve 把它的工具提供给其他客户端，比如 Claude Desktop。
• 服务器还可以提供以斜杠命令形式出现的提示词；参见 Claude Code 斜杠命令。
• 删除远程服务器会删掉 Claude Code 保存的令牌，但不会吊销它们；要吊销，先运行 claude mcp logout <name>。

MCP 与 token 用量

工具定义默认延迟加载：在 Claude 使用某个工具之前，上下文里只有工具名和服务器说明，所以配置一长串服务器比以前便宜。但每个服务器仍会占用一些上下文，所以在 /mcp 里禁用不用的服务器；如果有对应的 CLI，比如 gh、aws 或 gcloud，优先用 CLI，因为它完全不会增加工具列表。更多内容见如何减少 Claude Code 的 token 用量。

故障排查：服务器连不上时

• 显示需要认证：打开 /mcp 选择 Re-authenticate，或运行 claude mcp login <name>。
• 出现 "has a url but no type"：在 JSON 条目里加上 "type": "http"（或 sse、ws）；没有 type 时，Claude Code 会把它当作 stdio。
• stdio 服务器的参数被吞掉了：在服务器命令前加 --，这样 Claude Code 就不会把它们当成自己的参数解析。
• claude mcp list 中出现变量缺失警告：设置该变量，或给它加上 :-default 默认值。
• 项目服务器在 claude -p 中始终不加载：无头模式下没有确认提示，所以检查你的设置，或者用 --mcp-config 和 --strict-mcp-config 显式传入服务器。
• 用 claude mcp 添加的服务器名只能包含字母、数字、连字符和下划线。

让你的 AI 员工用上和你一样的工具

Claude Code 通过 MCP 连接你的 issue 跟踪系统、数据库或分析工具。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 会话变成有岗位、目标和工作时间的 AI 员工，并按心跳唤醒它，从看板上接手下一个 issue，同时可以使用你项目里的 MCP 服务器。

1. 提交 .mcp.json

   project 作用域的服务器会像在你的会话中一样，在员工的会话中加载；需要 OAuth 的服务器，先以交互方式登录一次。

2. 让心跳启动工作

   在工作时间内，员工每 15、30 或 60 分钟在同一个对话里醒来一次；参见如何让 Claude Code 主动工作。

3. 每个岗位只给它需要的

   SEO 员工拿到 Search Console；程序员拿到 GitHub 和 Sentry。阅读什么是 AI 员工。

Claude Code MCP 常见问题