向 Claude Code 添加 MCP 服务器（claude mcp add、.mcp.json、作用域）

HTTP 是远程服务器的推荐传输方式。Stdio 服务器作为本地进程在你的机器上运行。对于 stdio，-- 分隔符将 Claude 自身的选项（如 --transport、--env 和 --scope）与启动服务器的命令分开。-- 之后的所有内容都会原样传给服务器。

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP server with a Bearer token header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Local stdio server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• 使用 -e 或 --env 设置环境变量，例如 -e KEY=value。
• 如果服务器名紧跟在 --env 之后，CLI 会将该名称当作另一个键值对并拒绝。请在 --env 和名称之间放置另一个选项，例如 --transport stdio。
• --transport 和 --header 也接受简写形式 -t 和 -H。
• SSE 已弃用。你仍可传入 --transport sse 连接仅支持 SSE 的服务器。
• 如果你已有服务器的 JSON 配置，可使用 claude mcp add-json NAME 'JSON' 添加。

使用 -s 或 --scope 从三种作用域中选择一种。Local（默认）仅在当前项目中加载，存储在 ~/.claude.json 中。Project 存储在项目根目录的 .mcp.json 中，因此团队可通过版本控制获得它。User 同样存储在 ~/.claude.json 中，但会在你的所有项目中加载。当同一服务器名在多个作用域中定义时，local 优先于 project，project 优先于 user。

claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

.mcp.json 支持在 command、args、env、url 和 headers 中展开 ${VAR} 和 ${VAR:-default}。远程条目务必设置 type：有 url 但没有 type 的条目属于配置错误，因为 Claude Code 会把没有 type 的条目视为 stdio 服务器。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-weather": {
      "type": "stdio",
      "command": "/path/to/weather-cli",
      "args": ["--api-key", "${WEATHER_API_KEY}"],
      "env": { "CACHE_DIR": "/tmp" }
    }
  }
}

• Claude Code 在使用 .mcp.json 中的项目作用域服务器之前会请你批准。使用 claude mcp reset-project-choices 重置这些选择。
• 如果引用的变量未设置且没有默认值，服务器仍会以字面的 ${VAR} 文本加载，并且 claude mcp list 会显示警告。

Claude Code 支持远程服务器的 OAuth 2.0。添加需要登录的服务器后，在 Claude Code 中运行 /mcp，并在浏览器中完成登录。Token 会被安全存储并自动刷新。在 /mcp 菜单中使用 Clear authentication 可撤销访问。

claude mcp list
claude mcp get notion
claude mcp remove notion
claude mcp login sentry
claude mcp logout sentry

移除远程服务器也会删除 Claude Code 为其存储的 OAuth token。要从某个作用域中移除定义，请运行 claude mcp remove NAME --scope SCOPE。

• MCP_TIMEOUT 以毫秒为单位设置服务器启动超时，例如 MCP_TIMEOUT=10000 claude。
• MCP_TOOL_TIMEOUT 设置工具执行超时。可在某个服务器的 .mcp.json 条目中用 timeout 字段（毫秒）为其单独覆盖。
• 当 MCP 工具输出超过 10,000 token 时，Claude Code 会发出警告，并默认将其上限设为 25,000 token。使用 MAX_MCP_OUTPUT_TOKENS 提高上限。

export MAX_MCP_OUTPUT_TOKENS=50000
MCP_TIMEOUT=10000 claude