为 Claude Code 配置 MCP（Model Context Protocol）是扩展其能力、连接外部工具和数据源的关键步骤。您可以通过 claude mcp add 命令添加 HTTP 或 stdio 服务器，支持 OAuth 2.0 认证和作用域管理（local/project/user）。对于团队协作，可将配置存入 .mcp.json 文件并提交到版本控制。如果遇到工具输出过大，可以调整 MAX_MCP_OUTPUT_TOKENS 环境变量，或为特定工具添加 anthropic/maxResultSizeChars 注解。MCP Tool Search 默认按需加载工具定义，避免上下文窗口溢出。

Claude Code MCP 配置指南：连接外部工具和数据源

Claude Code 通过 Model Context Protocol (MCP) 连接外部工具和数据源。MCP 是一个开源协议，为 AI 工具集成提供标准接口，让你可以把 Claude Code 接入数据库、API、监控系统等上百种工具。

能做什么

接入 MCP 服务器后，你可以这样使用 Claude Code：

实现 JIRA ENG-4521 中描述的功能，并在 GitHub 创建 PR
检查 Sentry 和 Statsig，查看 ENG-4521 功能的使用情况
根据 PostgreSQL 数据库，找出使用过该功能的 10 个随机用户的邮件地址
根据 Figma 新设计稿更新标准邮件模板
给这 10 个用户创建 Gmail 草稿，邀请他们参与新功能的反馈

MCP 服务器还可以作为 Channel 把外部消息推入你的会话——让 Claude 在你不在时也能响应 Telegram 消息、Discord 聊天或 Webhook 事件。

查找和构建 MCP 服务器

在 Anthropic Directory 浏览经过审核的连接器。目录中的连接器使用与 Claude Code 相同的 MCP 基础设施，因此你可以用 claude mcp add 添加列出的任何远程服务器。

验证每个服务器是否可信再连接。获取外部内容的服务器可能会带来提示注入风险。

要构建自己的服务器，请参阅 MCP 服务器指南了解协议基础，以及 Claude 连接器构建文档了解认证、测试和 Directory 提交。

你也可以使用官方 mcp-server-dev 插件让 Claude 为你搭建一个服务器：

# 在会话中安装插件
/plugin install mcp-server-dev@claude-plugins-official

# 激活插件
/reload-plugins

# 构建 MCP 服务器
/mcp-server-dev:build-mcp-server

Claude 会询问你的使用场景，然后搭建一个远程 HTTP 或本地 stdio 服务器。

安装 MCP 服务器

MCP 服务器可以根据需要以三种不同方式配置。

方式一：添加远程 HTTP 服务器

HTTP 服务器是连接远程 MCP 服务器的推荐方式。这是云服务最广泛支持的传输方式。

# 基本语法
claude mcp add --transport http <名称> <URL>

# 连接 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

在 .mcp.json、~/.claude.json 或 claude mcp add-json 中配置 MCP 服务器时，type 字段接受 streamable-http 作为 http 的别名。MCP 规范使用名称 streamable-http 表示此传输，因此从服务器文档复制的配置无需修改即可使用。

方式二：添加远程 SSE 服务器（已废弃）

SSE（Server-Sent Events）传输已废弃。尽可能使用 HTTP 服务器。

# 基本语法
claude mcp add --transport sse <名称> <URL>

# 连接 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 带认证头
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

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

Stdio 服务器作为本地进程运行在你机器上。它们适合需要直接系统访问或自定义脚本的工具。

Claude Code 会在派生服务器的环境中设置 CLAUDE_PROJECT_DIR 环境变量为项目根目录，这样你的服务器可以解析项目相对路径而不依赖工作目录。此变量与钩子（Hooks）在 CLAUDE_PROJECT_DIR 中接收的目录相同。在服务器进程中读取它，例如 Node 中的 process.env.CLAUDE_PROJECT_DIR，或 Python 中的 os.environ["CLAUDE_PROJECT_DIR"]。你的服务器还可以调用 MCP roots/list 请求，该请求返回启动 Claude Code 的目录。

该变量在服务器环境中设置，不是 Claude Code 自身环境，因此在项目或用户作用域的 .mcp.json 的 command 或 args 中通过 ${VAR} 引用时需要默认值，如 ${CLAUDE_PROJECT_DIR:-.}。插件提供的 MCP 配置直接替换 ${CLAUDE_PROJECT_DIR}，不需要默认值。

# 基本语法
claude mcp add [options] <名称> -- <命令> [args...]

# 添加 Airtable 服务器
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

# Windows（原生）需要 cmd /c 包装
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

重要：选项顺序

所有选项（--transport、--env、--scope、--header）必须放在服务器名称前面。--（双破折号）将服务器名称与传递给 MCP 服务器的命令和参数分开。

例如：

claude mcp add --transport stdio myserver -- npx server → 运行 npx server

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080 → 运行 python server.py --port 8080，环境变量包含 KEY=value

这样可以避免 Claude 的标志与服务器标志冲突。

管理服务器

# 列出所有已配置服务器
claude mcp list

# 查看特定服务器详情
claude mcp get github

# 删除服务器
claude mcp remove github

# 在 Claude Code 内查看服务器状态
/mcp

/mcp 面板显示每个已连接服务器的工具计数，并标记那些声明了工具能力但实际上没有暴露任何工具的服务器。

如果请求需要使用仍在后台连接的服务器中的工具，Claude 会等待该服务器然后继续。默认启用工具搜索时，等待发生在 ToolSearch 调用内部。在没有工具搜索的配置中（如 Vertex AI、自定义 ANTHROPIC_BASE_URL、或 ENABLE_TOOL_SEARCH=false），Claude 改用 WaitForMcpServers 工具。

服务器名称 workspace 保留供内部使用。如果配置定义了同名服务器，Claude Code 会在加载时跳过它并显示警告，要求你重命名。

动态工具更新

Claude Code 支持 MCP list_changed 通知，允许 MCP 服务器动态更新其可用的工具、提示词和资源，无需断开并重新连接。当 MCP 服务器发送 list_changed 通知时，Claude Code 自动刷新该服务器的可用能力。

自动重连

如果 HTTP 或 SSE 服务器在会话中途断开，Claude Code 自动重连，采用指数退避：最多五次尝试，起始延迟为 1 秒，每次加倍。重连期间，服务器在 /mcp 中显示为“pending”。五次尝试失败后，服务器标记为失败，你可以从 /mcp 手动重试。Stdio 服务器是本地进程，不会自动重连。

相同的退避逻辑也适用于 HTTP 或 SSE 服务器在启动时初始连接失败。从 v2.1.121 开始，Claude Code 对暂时性错误（如 5xx 响应、连接被拒绝或超时）会重试初始连接最多三次，然后标记服务器为失败。认证错误和未找到错误不会重试，因为它们需要修改配置才能解决。

通过 Channels 推送消息

MCP 服务器还可以直接向你的会话推送消息，让 Claude 响应 CI 结果、监控告警或聊天消息等外部事件。要实现此功能，服务器声明 claude/channel 能力，并且你在启动时使用 --channels 标志启用它。使用官方支持的 channel 请参见 Channels，构建自己的 channel 请参见 Channels 参考。

提示：

使用 --scope 标志指定配置存储位置：

local（默认）：仅当前项目对你可用（旧版本中称为 project）

project：通过 .mcp.json 文件与项目所有人共享

user：跨所有项目对你可用（旧版本中称为 global）

使用 --env 标志设置环境变量（例如 --env KEY=value）

使用 MCP_TIMEOUT 环境变量配置 MCP 服务器启动超时（例如 MCP_TIMEOUT=10000 claude 设置 10 秒超时）

在服务器配置的 .mcp.json 条目中添加 timeout 字段（毫秒）来设置特定服务器的工具执行超时，例如 "timeout": 600000 表示十分钟。这会覆盖该服务器专用的 MCP_TOOL_TIMEOUT 环境变量

当 MCP 工具输出超过 10,000 个 token 时，Claude Code 会显示警告。要增加此限制，设置 MAX_MCP_OUTPUT_TOKENS 环境变量（例如 MAX_MCP_OUTPUT_TOKENS=50000）

使用 /mcp 对需要 OAuth 2.0 认证的远程服务器进行认证

每个服务器的 timeout 是每个工具调用的硬时钟限制，服务器的进度通知不会延长它。值低于 1000 会被限制为 1 秒。对于 HTTP 和 SSE 服务器，每个请求的获取首字节预算有 60 秒的最小值，不受此值影响，只有工具调用看门狗会遵守更小的值。

插件提供的 MCP 服务器

插件可以捆绑 MCP 服务器，在启用插件时自动提供工具和集成。插件 MCP 服务器与用户配置的服务器工作方式相同。

插件 MCP 服务器的工作方式：

插件在插件根目录的 .mcp.json 中或直接在 plugin.json 中内联定义 MCP 服务器
启用插件后，其 MCP 服务器自动启动
插件 MCP 工具与手动配置的 MCP 工具一起显示
插件服务器通过插件安装进行管理（不是通过 /mcp 命令）

示例插件 MCP 配置：

在插件根目录的 .mcp.json 中：

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

或者在 plugin.json 中内联：

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

插件 MCP 特性：

自动生命周期：会话启动时，已启用插件的服务器自动连接。如果在会话中启用或禁用插件，运行 /reload-plugins 来连接或断开其 MCP 服务器
环境变量：使用 ${CLAUDE_PLUGIN_ROOT} 表示捆绑的插件文件，${CLAUDE_PLUGIN_DATA} 表示持久状态（插件更新后仍保留），${CLAUDE_PROJECT_DIR} 表示稳定的项目根目录
用户环境访问：与手动配置的服务器访问相同的环境变量
多种传输类型：支持 stdio、SSE 和 HTTP 传输（传输支持因服务器而异）

查看插件 MCP 服务器：

# 在 Claude Code 中查看所有 MCP 服务器（包括插件提供的）
/mcp

插件服务器在列表中显示，并带有来自插件的指示。

插件 MCP 服务器的好处：

捆绑分发：工具和服务器打包在一起
自动设置：无需手动 MCP 配置
团队一致性：所有人安装插件后获得相同的工具

关于捆绑 MCP 服务器与插件的详细信息，请参见插件组件参考。

安装作用域

MCP 服务器可以在三种作用域下配置。选择的作用域控制服务器在哪些项目中加载，以及配置是否与团队共享。管理员还可以通过托管配置在企业级别部署服务器。

作用域	加载在	与团队共享	存储位置
本地	仅当前项目	否	`~/.claude.json`
项目	仅当前项目	是，通过版本控制	项目根目录的 `.mcp.json`
用户	所有项目	否	`~/.claude.json`

本地作用域

本地作用域是默认值。本地作用域的服务器仅在你添加它的项目中加载，且对你个人私有。Claude Code 将其存储在 ~/.claude.json 中该项目的路径下，因此同一服务器不会出现在你的其他项目中。对于个人开发服务器、实验性配置，或包含不想放入版本控制的凭据的服务器，使用本地作用域。

MCP 服务器的“本地作用域”不同于一般本地设置。MCP 本地作用域的服务器存储在 ~/.claude.json（你的主目录），而一般本地设置使用 .claude/settings.local.json（在项目目录中）。参见设置了解设置文件位置的详细信息。

# 添加本地作用域服务器（默认）
claude mcp add --transport http stripe https://mcp.stripe.com

# 明确指定本地作用域
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

该命令将服务器写入 ~/.claude.json 中当前项目的条目。以下示例显示了从 /path/to/your/project 运行时的结果：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

项目作用域

项目作用域的服务器通过在项目根目录存储 .mcp.json 文件实现团队协作。此文件设计为提交到版本控制，确保所有团队成员都可以访问相同的 MCP 工具和服务。当你添加项目作用域的服务器时，Claude Code 会自动创建或更新此文件，并采用适当的配置结构。

# 添加项目作用域服务器
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

生成的 .mcp.json 文件遵循标准格式：

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

出于安全原因，Claude Code 会在使用项目作用域服务器之前提示你批准。如果需要重置这些批准选择，请使用 claude mcp reset-project-choices 命令。

用户作用域

用户作用域的服务器存储在 ~/.claude.json 中，提供跨项目可访问性，使其在你机器上的所有项目中可用，同时对你的用户账户保持私有。此作用域适用于个人实用服务器、开发工具或你经常跨多个项目使用的服务。

# 添加用户作用域服务器
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

作用域层级和优先级

当同一服务器在多个地方定义时，Claude Code 只连接一次，使用优先级最高的来源：

本地作用域
项目作用域
用户作用域
插件提供的服务器
claude.ai 连接器

三个作用域按名称匹配重复项。插件和连接器按端点匹配，因此如果它们指向与上述服务器相同的 URL 或命令，则视为重复项。

环境变量扩展

Claude Code 支持在 .mcp.json 文件中进行环境变量扩展，允许团队共享配置同时保持对机器特定路径和敏感值（如 API 密钥）的灵活性。

支持的语法：

${VAR} - 展开为环境变量 VAR 的值
${VAR:-default} - 如果 VAR 已设置则展开其值，否则使用 default

扩展位置： 环境变量可以在以下位置扩展：

command - 服务器可执行文件路径
args - 命令行参数
env - 传递给服务器的环境变量
url - HTTP 服务器类型的 URL
headers - HTTP 服务器认证的请求头

带变量扩展的示例：

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

如果必需的环境变量未设置且没有默认值，Claude Code 将无法解析配置。

实战示例

使用 Sentry 监控错误

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

认证后使用：

/mcp

然后调试生产问题：

最近 24 小时最常见的错误是什么？

给我看看错误 ID abc123 的调用栈

哪次部署引入了这些新错误？

连接 GitHub 进行代码审查

GitHub 的远程 MCP 服务器通过传递 GitHub 个人访问令牌作为请求头进行认证。要获取令牌，打开 GitHub 令牌设置，生成一个具有访问你希望 Claude 操作的仓库权限的细粒度令牌，然后添加服务器：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

然后使用 GitHub：

审查 PR #456 并提出改进建议

为刚发现的 bug 创建新 issue

列出分配给我的所有开放 PR

查询 PostgreSQL 数据库

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

然后自然语言查询：

本月总收入是多少？

显示 orders 表的结构

找出 90 天内没有购买记录的用户

认证远程 MCP 服务器

许多基于云的 MCP 服务器需要认证。Claude Code 支持 OAuth 2.0 安全连接。

当服务器响应 401 Unauthorized 或 403 Forbidden 时，Claude Code 将该远程服务器标记为需要认证。任一状态码都会在 /mcp 中标记服务器，以便你完成 OAuth 流程。自定义服务器如果返回指向其授权服务器的 WWW-Authenticate 请求头，也会像其他远程服务器一样自动发现。

例如：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

在 Claude Code 中使用命令：

/mcp

然后按照浏览器中的步骤登录。

提示：

认证令牌安全存储并自动刷新

使用 /mcp 菜单中的“清除认证”以撤销访问

如果浏览器未自动打开，请复制提供的 URL 并手动打开

如果认证后浏览器重定向失败并显示连接错误，请将浏览器地址栏中的完整回调 URL 粘贴到 Claude Code 中显示的 URL 提示中

OAuth 认证适用于 HTTP 服务器

固定 OAuth 回调端口

某些 MCP 服务器需要预先注册的特定重定向 URI。默认情况下，Claude Code 为 OAuth 回调选择一个随机可用端口。使用 --callback-port 固定端口，使其匹配预注册的格式为 http://localhost:PORT/callback 的重定向 URI。

你可以单独使用 --callback-port（使用动态客户端注册），也可以与 --client-id 一起使用（使用预配置凭据）。

# 固定回调端口，使用动态客户端注册
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

使用预配置 OAuth 凭据

某些 MCP 服务器不支持通过动态客户端注册自动设置 OAuth。如果遇到错误“Incompatible auth server: does not support dynamic client registration”，说明服务器需要预配置凭据。Claude Code 也支持使用客户端 ID 元数据文档的服务器，并自动发现它们。如果自动发现失败，首先通过服务器的开发者门户注册 OAuth 应用，然后在添加服务器时提供凭据。

# 通过开发者门户创建应用，记下 client ID 和 client secret
# 许多服务器还需要重定向 URI。选择一个端口并注册重定向 URI，格式为 http://localhost:PORT/callback，在下一步中使用相同的 --callback-port

# 使用 --client-id 传递应用 client ID。--client-secret 标志会提示以掩码输入输入密钥
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

# 或者将 oauth 对象包含在 JSON 配置中，并使用 --client-secret 标志
claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

# 仅固定端口而不传递 client ID
claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

# 通过环境变量设置 secret 以跳过交互提示
MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

运行 /mcp 并按照浏览器登录流程操作。

提示：

Client secret 安全存储在你的系统钥匙串（macOS）或凭据文件中，不存储在配置中

如果服务器使用公共 OAuth 客户端且没有 secret，则仅使用 --client-id，不使用 --client-secret

--callback-port 可以与 --client-id 一起使用或单独使用

这些标志仅适用于 HTTP 和 SSE 传输，对 stdio 服务器无效

使用 claude mcp get <名称> 验证 OAuth 凭据是否已配置

覆盖 OAuth 元数据发现

将 Claude Code 指向特定的 OAuth 授权服务器元数据 URL，以绕过默认发现链。当 MCP 服务器的标准端点错误时，或者当你希望将发现路由到内部代理时，设置 authServerMetadataUrl。默认情况下，Claude Code 首先在 /.well-known/oauth-protected-resource 检查 RFC 9728 受保护资源元数据，然后回退到 /.well-known/oauth-authorization-server 的 RFC 8414 授权服务器元数据。

在 .mcp.json 中服务器配置的 oauth 对象中设置 authServerMetadataUrl：

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

URL 必须使用 https://。authServerMetadataUrl 需要 Claude Code v2.1.64 或更高版本。元数据 URL 的 scopes_supported 会覆盖上游服务器声明的范围。

限制 OAuth 作用域

设置 oauth.scopes 以固定 Claude Code 在授权流程中请求的作用域。这是将 MCP 服务器限制为安全团队批准的、上游授权服务器声明更多作用域时的子集的受支持方式。值是一个由空格分隔的字符串，匹配 RFC 6749 §3.3 中 scope 参数格式。

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes 优先于 authServerMetadataUrl 和服务器在 /.well-known 发现的作用域。不设置则让 MCP 服务器决定请求的作用域集合。

如果授权服务器在 scopes_supported 中声明了 offline_access，Claude Code 会将其附加到固定的作用域中，以便访问令牌可以不经过新的浏览器登录而刷新。

如果服务器稍后针对工具调用返回 403 insufficient_scope，Claude Code 会使用相同的固定作用域重新认证。如果需要的工具需要 pin 之外的作用域，请扩大 oauth.scopes。

使用动态请求头进行自定义认证

如果 MCP 服务器使用非 OAuth 的认证方案（如 Kerberos、短期令牌或内部 SSO），使用 headersHelper 在连接时生成请求头。Claude Code 运行该命令并将其输出合并到连接请求头中。

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

命令也可以是内联的：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

要求：

命令必须将字符串键值对的 JSON 对象写入 stdout
命令在 shell 中运行，超时 10 秒
动态请求头会覆盖同名的静态 headers

每次连接（会话启动和重连）时，辅助程序都会重新运行。没有缓存，因此你的脚本负责任何令牌重用。

Claude Code 在执行辅助程序时设置这些环境变量：

变量	值
`CLAUDE_CODE_MCP_SERVER_NAME`	MCP 服务器名称
`CLAUDE_CODE_MCP_SERVER_URL`	MCP 服务器的 URL

利用这些变量编写一个支持多个 MCP 服务器的辅助脚本。

headersHelper 执行任意 shell 命令。在项目或本地作用域定义时，仅在你接受工作区信任对话框后才会运行。

从 JSON 配置添加 MCP 服务器

如果你有 MCP 服务器的 JSON 配置，可以直接添加：

# 基本语法
claude mcp add-json <名称> '<json>'

# 添加 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-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# 添加带有预配置 OAuth 凭据的 HTTP 服务器
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

验证：

claude mcp get weather-api

提示：

确保 JSON 在你的 shell 中正确转义

JSON 必须符合 MCP 服务器配置模式

使用 --scope user 将服务器添加到用户配置而不是项目特定配置

从 Claude Desktop 导入 MCP 服务器

如果你已经在 Claude Desktop 中配置了 MCP 服务器，可以导入它们：

# 基本语法
claude mcp add-from-claude-desktop

运行命令后，你会看到一个交互式对话框，允许你选择要导入的服务器。

验证导入：

claude mcp list

提示：

此功能仅适用于 macOS 和 Windows Subsystem for Linux (WSL)

它从这些平台的标准位置读取 Claude Desktop 配置文件

使用 --scope user 标志将服务器添加到用户配置

导入的服务器将具有与 Claude Desktop 中相同的名称

如果存在同名服务器，将获得数字后缀（如 server_1）

从 Claude.ai 导入 MCP 服务器

如果你已经使用 Claude.ai 账户登录 Claude Code，则在 Claude.ai 中添加的 MCP 服务器会自动在 Claude Code 中可用：

在 claude.ai/customize/connectors 添加服务器。Team 和 Enterprise 计划只有管理员可以添加服务器。
完成 Claude.ai 中任何必需的认证步骤。
在 Claude Code 中使用命令：

/mcp

Claude.ai 服务器出现在列表中，并带有来自 Claude.ai 的指示。

Claude.ai 连接器仅在当前活跃的认证方法是你的 Claude.ai 订阅时才会被获取。当 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、apiKeyHelper 或第三方提供商（如 Bedrock 或 Vertex）激活时，即使你之前运行过 /login，也不会加载这些连接器。如果 /mcp 没有列出你添加的连接器，请运行 /status 确认哪个认证方法活跃，取消设置该环境变量或删除 apiKeyHelper 设置，然后运行 /login 选择你的 Claude.ai 账户。

你在 Claude Code 中添加的服务器优先于指向同一 URL 的 claude.ai 连接器。当发生这种情况时，/mcp 会将连接器列为隐藏，并显示如何移除重复项（如果你想改用连接器）。

要禁用 Claude Code 中的 claude.ai MCP 服务器，将环境变量 ENABLE_CLAUDEAI_MCP_SERVERS 设置为 false：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

将 Claude Code 用作 MCP 服务器

你可以将 Claude Code 本身用作一个 MCP 服务器，其他应用程序可以连接：

# 将 Claude 作为 stdio MCP 服务器启动
claude mcp serve

你可以通过将此配置添加到 claude_desktop_config.json 文件，在 Claude Desktop 中使用：

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

配置可执行文件路径：command 字段必须引用 Claude Code 可执行文件。如果 claude 命令不在系统 PATH 中，你需要指定可执行文件的完整路径。

要查找完整路径：
which claude
然后在配置中使用完整路径：
{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}
没有正确的可执行文件路径，你会遇到错误，如 spawn claude ENOENT。

提示：

服务器提供对 Claude 工具（如 View、Edit、LS 等）的访问

在 Claude Desktop 中，尝试让 Claude 读取目录中的文件、进行编辑等

注意，此 MCP 服务器仅向你的 MCP 客户端暴露 Claude Code 的工具，因此你的客户端负责实现单个工具调用的用户确认

MCP 输出限制和警告

当 MCP 工具产生大量输出时，Claude Code 帮助管理 token 使用，防止溢出对话上下文：

输出警告阈值：Claude Code 在任何 MCP 工具输出超过 10,000 个 token 时显示警告
可配置限制：你可以使用 MAX_MCP_OUTPUT_TOKENS 环境变量调整最大允许的 MCP 输出 token
默认限制：默认最大值为 25,000 个 token
范围：环境变量适用于未声明自己限制的工具。设置了 anthropic/maxResultSizeChars 的工具使用该值作为文本内容，无论 MAX_MCP_OUTPUT_TOKENS 设置为何。返回图像数据的工具仍受 MAX_MCP_OUTPUT_TOKENS 限制

要提高对于产生大量输出的工具的限制：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

这在处理以下 MCP 服务器时特别有用：

查询大型数据集或数据库
生成详细报告或文档
处理大量日志文件或调试信息

提高特定工具的输出限制

如果你正在构建 MCP 服务器，可以通过在工具的 tools/list 响应条目中设置 _meta["anthropic/maxResultSizeChars"] 来允许单个工具返回大于默认持久化到磁盘阈值的结果。Claude Code 会将工具阈值提高到注释值，上限为 500,000 个字符。

这对于返回本身很大但必需的输出的工具很有用，例如数据库模式或完整的文件树。如果没有注释，超过默认阈值的结果会持久化到磁盘，并在对话中替换为文件引用。

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

对于文本内容，注解独立于 MAX_MCP_OUTPUT_TOKENS 工作，因此用户不需要为声明它的工具提高环境变量。返回图像数据的工具仍受 token 限制。

如果你经常遇到特定不受控 MCP 服务器的输出警告，考虑提高 MAX_MCP_OUTPUT_TOKENS 限制。你也可以要求服务器作者添加 anthropic/maxResultSizeChars 注释或对响应进行分页。注释对返回图像内容的工具没有影响；对于这些工具，提高 MAX_MCP_OUTPUT_TOKENS 是唯一的选择。

响应 MCP 诱发请求

MCP 服务器可以在任务进行中通过诱发请求向你请求结构化输入。当服务器需要无法自行获取的信息时，Claude Code 会显示交互式对话框，并将你的响应传递回服务器。你这边不需要任何配置：当服务器请求时，诱发对话框会自动出现。

服务器可以通过两种方式请求输入：

表单模式：Claude Code 显示由服务器定义的表单字段对话框（例如用户名和密码提示）。填写字段并提交。
URL 模式：Claude Code 打开浏览器 URL 进行认证或批准。在浏览器中完成流程，然后在 CLI 中确认。

要自动响应诱发请求而不显示对话框，请使用 Elicitation 钩子。

如果你正在构建使用诱发请求的 MCP 服务器，请参见 MCP 诱发规范了解协议细节和模式示例。

使用 MCP 资源

MCP 服务器可以暴露资源，你可以使用 @ 引用，就像引用文件一样。

引用 MCP 资源

在提示中键入 @ 以查看所有已连接 MCP 服务器中的可用资源。资源与文件一起出现在自动完成菜单中。
使用 @server:protocol://resource/path 格式引用资源：

你能分析 @github:issue://123 并建议修复方案吗？

请查阅 @docs:file://api/authentication 中的 API 文档

你可以在一个提示中引用多个资源：

对比 @postgres:schema://users 和 @docs:file://database/user-model

提示：

引用资源时，资源会自动获取并作为附件包含

资源路径在 @ 引用自动完成中支持模糊搜索

当服务器支持资源时，Claude Code 会自动提供列出和读取 MCP 资源的工具

资源可以包含 MCP 服务器提供的任何类型内容（文本、JSON、结构化数据等）

使用 MCP 提示作为命令

MCP 服务器可以暴露提示，这些提示在 Claude Code 中作为命令可用。

执行 MCP 提示

键入 / 查看所有可用命令，包括来自 MCP 服务器的命令。MCP 提示以 /mcp__servername__promptname 格式出现。
使用：

/mcp__github__list_prs

许多提示接受参数。在命令后以空格分隔传递：

/mcp__github__pr_review 456

/mcp__jira__create_issue "登录流程 bug" high

提示：

MCP 提示从已连接的服务器动态发现

参数基于提示的定义参数进行解析

提示结果直接注入对话

服务器和提示名称被规范化（空格变为下划线）

配置工具搜索

工具搜索保持 MCP 上下文使用量较低，方法是将工具定义推迟直到 Claude 需要它们。会话启动时只加载工具名称，因此添加更多 MCP 服务器对上下文窗口影响最小。

工具搜索默认启用。MCP 工具被推迟而不是提前加载到上下文中，Claude 使用搜索工具在任务需要时发现相关工具。只有 Claude 实际使用的工具会进入上下文。从你的角度来看，MCP 工具的工作方式与之前完全相同。

如果你更喜欢基于阈值的加载，设置 ENABLE_TOOL_SEARCH=auto 可以在工具适合上下文窗口的 10% 以内时提前加载模式，仅推迟溢出的部分。参见下表了解所有选项。

控制工具搜索行为的环境变量 ENABLE_TOOL_SEARCH：

值	行为
(未设置)	所有 MCP 工具推迟并按需加载。在 Vertex AI 上或 `ANTHROPIC_BASE_URL` 为非第一方主机时回退到提前加载
`true`	所有 MCP 工具推迟。即使在 Vertex AI 和代理后面，Claude Code 也会发送测试版标头。在早于 Sonnet 4.5 或 Opus 4.5 的 Vertex AI 模型上请求失败，或在不支持 `tool_reference` 块的代理上失败
`auto`	阈值模式：如果工具适合上下文窗口的 10%，则提前加载；否则推迟
`auto:N`	阈值模式，自定义百分比，`N` 为 0-100。例如 `auto:5` 表示 5%
`false`	所有 MCP 工具提前加载，无推迟

# 自定义 5% 阈值
ENABLE_TOOL_SEARCH=auto:5 claude

# 完全禁用工具搜索
ENABLE_TOOL_SEARCH=false claude

也可以在你的 settings.json env 字段中设置该值。

你还可以专门禁用 ToolSearch 工具：

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

免除服务器的推迟

如果某个服务器的工具应该始终对 Claude 可见而无需搜索步骤，请在该服务器配置中设置 alwaysLoad 为 true。该服务器的每个工具都会在会话启动时加载到上下文中，无论 ENABLE_TOOL_SEARCH 设置如何。仅对 Claude 每次轮次都需要的小部分工具使用此设置，因为每个提前加载的工具都会消耗其他对话可用的上下文。

以下 .mcp.json 条目使一个 HTTP 服务器免除推迟，而其他服务器保持推迟：

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

alwaysLoad 字段适用于所有服务器类型，需要 Claude Code v2.1.121 或更高版本。MCP 服务器还可以通过在工具的 _meta 对象中包含 "anthropic/alwaysLoad": true 来将单个工具标记为始终加载，这仅对该工具有相同效果。

设置 alwaysLoad: true 还会阻止启动直到服务器连接，上限为标准 5 秒连接超时。即使 MCP 启动默认是非阻塞的，因为工具必须在构建第一个提示时就存在。其他服务器继续在后台连接。

企业级管理

对于需要集中控制用户可以连接哪些 MCP 服务器的组织，请参见托管 MCP 配置。它涵盖了使用 managed-mcp.json 部署固定服务器集合、使用 allowedMcpServers 和 deniedMcpServers 限制服务器，以及服务器被阻止时用户会看到什么。

常见问题

如何为 Claude Code 配置 MCP 服务器？

使用 claude mcp add 命令。对于 HTTP 服务器：claude mcp add --transport http <名称> <URL>。对于本地工具：claude mcp add --transport stdio <名称> -- <命令>。使用 --scope 定义作用范围（local/project/user），使用 --env 设置环境变量，使用 --header 添加认证头。

Claude Code MCP 服务器认证失败怎么解决？

常见的 OAuth 认证问题：1）确保使用了正确的 client-id 和回调端口（--callback-port）；2）如果遇到“Incompatible auth server”错误，说明服务器需要预配置凭据，通过开发者门户注册应用；3）认证后浏览器重定向失败时，从浏览器地址栏复制完整回调 URL 粘贴到 Claude Code 中；4）认证令牌自动刷新，可以在 /mcp 菜单中清除认证重新授权。

使用 MCP 工具输出过大导致上下文溢出怎么处理？

默认输出警告阈值是 10,000 tokens，最大输出限制是 25,000 tokens。可以通过设置 export MAX_MCP_OUTPUT_TOKENS=50000 提高限制。如果针对特定工具，可以在 MCP 服务器 tools/list 响应中添加 _meta.anthropic/maxResultSizeChars 注解，上限 500,000 字符。另外 MCP Tool Search 默认启用，按需加载工具定义可以减小上下文压力。

Claude Code MCP 配置指南：连接外部工具和数据源 #

能做什么 #

查找和构建 MCP 服务器 #

安装 MCP 服务器 #

方式一：添加远程 HTTP 服务器 #

方式二：添加远程 SSE 服务器（已废弃） #

方式三：添加本地 stdio 服务器 #

管理服务器 #

动态工具更新 #

自动重连 #

通过 Channels 推送消息 #

插件提供的 MCP 服务器 #

安装作用域 #

本地作用域 #

项目作用域 #

用户作用域 #

作用域层级和优先级 #

环境变量扩展 #

实战示例 #

使用 Sentry 监控错误 #

连接 GitHub 进行代码审查 #

查询 PostgreSQL 数据库 #

认证远程 MCP 服务器 #

固定 OAuth 回调端口 #

使用预配置 OAuth 凭据 #

覆盖 OAuth 元数据发现 #

限制 OAuth 作用域 #

使用动态请求头进行自定义认证 #

从 JSON 配置添加 MCP 服务器 #

从 Claude Desktop 导入 MCP 服务器 #

从 Claude.ai 导入 MCP 服务器 #

将 Claude Code 用作 MCP 服务器 #

MCP 输出限制和警告 #

提高特定工具的输出限制 #

响应 MCP 诱发请求 #

使用 MCP 资源 #

引用 MCP 资源 #

使用 MCP 提示作为命令 #

执行 MCP 提示 #

配置工具搜索 #

免除服务器的推迟 #

企业级管理 #

常见问题 #

如何为 Claude Code 配置 MCP 服务器？ #

Claude Code MCP 服务器认证失败怎么解决？ #

使用 MCP 工具输出过大导致上下文溢出怎么处理？ #