它到底是什么

claude mcp 是 Claude Code CLI 的核心子命令组，用于在本地注册、管理、查看、移除 MCP（Model Context Protocol）服务器，以及将 Claude Code 本身暴露为 MCP 服务端。

MCP 是 Anthropic 主导的开放标准，允许 AI 以结构化方式调用外部工具、数据库、API。通过 claude mcp 系列命令，可以：

• 接入 GitHub、Sentry、Notion、Jira、PostgreSQL 等数百个云服务
• 把自建脚本或本地二进制文件作为 MCP 服务暴露给 Claude
• 把 Claude Code 的内置工具反向暴露给 Claude Desktop、Cursor 等其他客户端

平台要求：

• 通过 Claude Code CLI 使用,所有子命令在 shell 中运行(具体版本号要求以官方 changelog 为准,本指南不臆造版本下限)
• add-from-claude-desktop 仅支持 macOS 和 WSL（Windows Subsystem for Linux）
• OAuth 相关 flag 仅对 http/sse transport 有效
• claude mcp serve 在所有平台可用

怎么触发 / 怎么使用

所有子命令在 shell 中以 claude mcp <subcommand> 形式运行，不需要进入 Claude Code 交互会话。

1. claude mcp add — 添加服务器

HTTP（推荐，适用于云端服务）

# 基础语法
claude mcp add --transport http <name> <url>

# 添加 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带 Bearer token 认证头
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# 指定 project scope（写入 .mcp.json，可提交到 git）
claude mcp add --transport http sentry --scope project https://mcp.sentry.dev/mcp

# 指定 user scope（全局所有项目可用）
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

stdio（本地进程，适用于本地工具和自建脚本）

# 基础语法：选项在前，-- 后接命令
claude mcp add [options] <name> -- <command> [args...]

# 使用 npx 安装并运行
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

# 本地 Python 脚本
claude mcp add --transport stdio my-tools \
  -- python /path/to/server.py --port 8080

# 传多个环境变量
claude mcp add --transport stdio db \
  --env DB_URL=postgres://user:pass@host/db \
  --env DB_POOL_SIZE=5 \
  -- npx -y @bytebase/dbhub

# Windows 下必须用 cmd /c 包装 npx
claude mcp add --transport stdio my-server -- cmd /c npx -y some-mcp-package

SSE（已废弃，尽量迁移到 HTTP）

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

WebSocket（仅通过 add-json 或直接编辑 .mcp.json 配置）

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer TOKEN"}}'

2. claude mcp list — 查看所有服务器

claude mcp list

输出示例：

✓ github     http   https://api.githubcopilot.com/mcp/
✓ sentry     http   https://mcp.sentry.dev/mcp
✗ broken-db  stdio  (failed to connect)
⏸ new-tool   stdio  Pending approval

3. claude mcp get <name> — 查看指定服务器详情

claude mcp get github

输出包含 transport 类型、URL/command、scope、认证状态、连接状态。官方记录的连接状态有:✓ Connected、! Needs authentication、✗ Failed to connect、✗ Connection error、⏸ Pending approval(无 Rejected 状态)。

4. claude mcp remove <name> — 移除服务器

claude mcp remove github
# 移除 user scope 的服务器
claude mcp remove hubspot --scope user

5. claude mcp add-json <name> '<json>' — JSON 方式添加

适用于批量配置或 CI 自动化：

# HTTP 服务器
claude mcp add-json weather-api \
  '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# stdio 服务器
claude mcp add-json local-tools \
  '{"type":"stdio","command":"/usr/local/bin/my-tool","args":["--verbose"],"env":{"LOG_LEVEL":"debug"}}'

# 带 OAuth 预配置
claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"YOUR_ID","callbackPort":8080}}' \
  --client-secret

6. claude mcp add-from-claude-desktop — 从 Claude Desktop 导入

claude mcp add-from-claude-desktop
# 会弹出交互选择界面，选择要导入的服务器
# 加 --scope user 写入全局配置
claude mcp add-from-claude-desktop --scope user

7. claude mcp serve — 将 Claude Code 本身作为 MCP 服务端

# 启动 stdio MCP 服务
claude mcp serve

在 Claude Desktop 的 claude_desktop_config.json 中配置：

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/usr/local/bin/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

如果 claude 不在 PATH 中，用 which claude 获取完整路径，避免 spawn claude ENOENT 错误。

8. claude mcp reset-project-choices — 重置 project scope 授权记录

claude mcp reset-project-choices

重置后下次进入会话时重新触发 .mcp.json 服务器的信任确认弹窗。

9. claude mcp login <name> / claude mcp logout <name> — 命令行认证(v2.1.186+)

自 v2.1.186 起,可直接在 shell 里跑某个已配置 remote 服务器的 OAuth 流程,无需进入会话打开 /mcp 面板:

claude mcp login sentry      # 运行该服务器的 OAuth 授权流程
claude mcp logout sentry     # 清除已存储的凭据

claude mcp login <name> 触发 <name> 这个已配置服务器的 OAuth 授权;完成后凭据存于本地,claude mcp logout <name> 用于事后清除。

SSH / 无浏览器环境:自 v2.1.191 起,命令会检测本机是否有可用浏览器(如 SSH 会话、无显示服务器的 Linux),无浏览器时改为打印授权 URL而非尝试打开浏览器——在本地机器打开该 URL,再把浏览器地址栏里完整的 redirect URL 粘回提示符。粘贴这一步需要交互式终端,所以用 ssh -t 连接。即便本机检测到浏览器,也可加 --no-browser 强制走 URL 提示:

claude mcp login sentry --no-browser

监控 / 控制 / 键位

/mcp 是在 Claude Code 交互会话内使用的命令（非 CLI），用于查看和操作 MCP 服务器状态：

HTTP 404 错误现在显示 URL（v2.1.191）：MCP server 连接报 HTTP 404 时，旧版只给一个干巴巴的 404 难以定位。自 v2.1.191 起，404 错误信息会带上实际请求的 URL 并指向你的 MCP 配置，便于一眼看出是 endpoint 路径写错（如 /mcp 写成 /mcp/ 或漏了路径段）。来源：Claude Code changelog v2.1.191 —— "Improved MCP error messages: HTTP 404 errors now show the URL and point to your MCP config"。

启动时认证提示(v2.1.193):v2.1.193 起,若有 MCP 服务器需要认证,Claude Code 会在启动时显示一条提示,指向 /mcp 让你直接去完成 OAuth 授权,而不必等到工具调用失败才发现服务器未连上。来源:Claude Code changelog v2.1.193 "Added a startup notice when MCP servers need authentication, pointing at /mcp"。

服务器断连后,官方文档说明可通过 /mcp 手动重连。早期本指南列出的"自动重连指数退避(最多 5 次、初始 1s、每次翻倍)"、@server:protocol://resource/path 资源引用语法、/mcp__servername__promptname 命令格式等具体细节均无官方/三方来源佐证,已移除。

保存 / 配置 / 集成

配置文件位置

local 和 user 都写在 ~/.claude.json 里，区别在于前者按项目路径键控，后者是全局键。

.mcp.json 格式

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      },
      "timeout": 600000,
      "alwaysLoad": false
    },
    "local-tool": {
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/tools/server.js"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

环境变量展开语法：

• ${VAR} — 直接展开，未定义则报错
• ${VAR:-default} — 有回退默认值

展开位置：command、args、env、url、headers

关键环境变量

Tool Search 配置

工具延迟加载（Tool Search）用于降低上下文消耗。据 builder.io,默认值为 auto:

alwaysLoad: true(特定服务器强制预加载)现已见于官方 MCP 文档:在某 server 的 .mcp.json 配置里设 alwaysLoad: true,则该 server 的全部工具在会话启动时无视 ENABLE_TOOL_SEARCH 一律加载进上下文。官方建议仅对"每轮都要用的少量工具"开启,因为每个预加载工具都占上下文。来源:官方 MCP 文档。

动态认证头（headersHelper）

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-auth-headers.sh"
    }
  }
}

脚本须向 stdout 输出 JSON 对象(字符串键值对)。headersHelper 字段仅见于部分第三方文章,官方文档未收录;早期本指南声称的"10 秒超时、每次连接重新执行、无缓存"等具体行为无来源佐证,已移除——实际超时/缓存行为请实测确认。

headersHelper 401/403 自动重连(v2.1.193):v2.1.193 改进了 headersHelper 的认证流程——当某次工具调用返回 401/403(凭据过期或失效)时,headersHelper 脚本会自动重新执行并重连,无需手动 /mcp → Retry。这对短时效 token(如临时凭据、OIDC 短 token)尤其有用。来源:Claude Code changelog v2.1.193 "Improved MCP headersHelper auth: the helper now re-runs and reconnects automatically when a tool call returns 401/403"。

运行约束 / 限制

跟同类原语对比

经典使用场景

• 团队统一工具链：在项目根目录维护 .mcp.json（--scope project），把 GitHub、Sentry、Jira 等服务地址提交 git，所有成员 git pull 后即刻获得相同 MCP 工具集，API key 各自通过环境变量 ${GITHUB_TOKEN} 注入。
• 本地数据库直连：claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgres://..." 后，直接用自然语言查询生产库 schema 或排查慢查询。
• 将 Claude Code 工具暴露给其他 AI 客户端：claude mcp serve 配合 Claude Desktop claude_desktop_config.json，使 Claude Desktop 也能调用 View、Edit、LS 等文件操作工具。
• CI 自动化注入服务器：claude mcp add-json 配合 MCP_CLIENT_SECRET 环境变量，在 CI pipeline 里无交互地注册需要 OAuth 的远端 MCP 服务。
• 个人跨项目通用工具：--scope user 添加个人惯用的本地脚本（代码格式化、截图工具等），一次配置，所有项目自动继承，无需重复设置。

常见坑

1. flag 顺序错误导致 stdio 命令无法启动：claude mcp add myserver --env K=V -- npx server 正确；claude mcp add myserver -- npx server --env K=V 错误——--env 会被传给 npx 而非 Claude。所有 Claude flag 必须在服务器名之前，-- 必须紧接服务器名之后。

2. Windows 上 stdio 服务器立即断连：直接用 npx 在 Windows CMD 环境下无法正常通信，必须包装为 cmd /c npx -y some-mcp-package，否则出现 "Connection closed" 错误。

3. dotenv v17+ 污染 stdout 导致 JSON 解析失败：dotenv 17 开始默认向 stdout 输出调试信息，破坏 stdio transport 的 JSON 协议。修复：在服务端启动命令前设置 DOTENV_CONFIG_QUIET=true，或将服务端日志全部改为 console.error()（stderr 不影响 stdio 通信）。

4. project scope 服务器需要交互式确认：.mcp.json 中新增的服务器首次加载时，Claude Code 会显示信任确认提示，claude mcp list 显示 ⏸ Pending approval。必须以交互模式启动一次 claude 才能完成审批，无法在 headless/非交互环境中绕过。用 claude mcp reset-project-choices 可重置所有审批记录。

5. 同名服务器被高优先级 scope 静默覆盖：如果 local scope 和 project scope 都定义了名为 github 的服务器，Claude Code 只使用 local 那条，不合并字段。排查工具不生效时，先 claude mcp list 确认实际加载的是哪条配置。

关闭 / 退出 / 卸载

• 移除单个服务器：claude mcp remove <name> 或 claude mcp remove <name> --scope user/project
• 移除 project scope 配置文件：删除或清空 .mcp.json；若已提交 git，需 commit 删除操作后团队成员 pull 才生效
• 停止 claude mcp serve：直接 Ctrl+C 中断进程
• 禁用工具延迟加载（全部预加载）：ENABLE_TOOL_SEARCH=false claude

来源

• Connect Claude Code to tools via MCP — 官方文档
• Claude Code MCP Commands — MCPBundles Docs
• Claude Code MCP Servers: How to Connect, Configure, and Use Them — Builder.io
• claude-mcp-guide — GitHub (justinwlin)
• Add MCP Servers to Claude Code — MCPcat 配置指南