文档索引

在此处获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

通过 MCP 将 Claude Code 连接到工具

了解如何通过模型上下文协议将 Claude Code 连接到你的工具。

Claude Code 可以通过模型上下文协议（MCP）连接到数百个外部工具和数据源，这是一个用于 AI 工具集成的开源标准。MCP 服务器使 Claude Code 能够访问你的工具、数据库和 API。

当你发现自己从另一个工具（如问题跟踪器或监控仪表板）将数据复制到聊天中时，请连接服务器。连接后，Claude 可以直接读取和操作该系统，而不是根据你粘贴的内容工作。

使用 MCP 可以做什么

连接 MCP 服务器后，你可以要求 Claude Code：

从问题跟踪器实现功能："Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."
分析监控数据："Check Sentry and Statsig to check the usage of the feature described in ENG-4521."
查询数据库："Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."
集成设计："Update our standard email template based on the new Figma designs that were posted in Slack"
自动化工作流："Create Gmail drafts inviting these 10 users to a feedback session about the new feature."
响应外部事件：MCP 服务器还可以充当通道，将消息推送到你的会话中，以便 Claude 在你离开时响应 Telegram 消息、Discord 聊天或 webhook 事件。

查找和构建 MCP 服务器

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

Warning

在连接之前验证你信任每个服务器。获取外部内容的服务器可能使你面临提示注入风险。

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

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

安装插件
在 Claude Code 会话中，运行：
```
/plugin install mcp-server-dev@claude-plugins-official
```
如果 Claude Code 报告找不到市场，先运行 /plugin marketplace add anthropics/claude-plugins-official，然后重试安装。安装后，运行 /reload-plugins 在当前会话中激活它。
运行构建技能
```
/mcp-server-dev:build-mcp-server
```
Claude 会询问你的用例并搭建远程 HTTP 或本地 stdio 服务器。

安装 MCP 服务器

MCP 服务器可以根据你的需求以三种不同方式配置：

选项 1：添加远程 HTTP 服务器

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

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

# 实际示例：连接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 使用 Bearer 令牌的示例
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 中通过 JSON 配置 MCP 服务器时，type 字段接受 streamable-http 作为 http 的别名。MCP 规范使用 streamable-http 作为此传输的名称，因此从服务器文档复制的配置无需修改即可使用。

选项 2：添加远程 SSE 服务器

Warning

SSE（Server-Sent Events）传输已弃用。请改用 HTTP 服务器（如可用）。

# 基本语法
claude mcp add --transport sse <name> <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"

选项 3：添加本地 stdio 服务器

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

Claude Code 在生成的服务器环境中将 CLAUDE_PROJECT_DIR 设置为项目根目录，因此你的服务器可以解析项目相对路径而不依赖工作目录。这与钩子在其 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 中通过 {{CONTENT}}amp;#123;VAR} 扩展引用它需要默认值，如 ${CLAUDE_PROJECT_DIR:-.}。插件提供的 MCP 配置直接替换 {{CONTENT}}amp;#123;CLAUDE_PROJECT_DIR}，不需要默认值。

# 基本语法
claude mcp add [options] <name> -- <command> [args...]

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

Note

重要：选项顺序

所有选项（--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 的标志和服务器的标志之间的冲突。

管理你的服务器

配置后，你可以使用以下命令管理 MCP 服务器：

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

# 获取特定服务器的详情
claude mcp get github

# 移除服务器
claude mcp remove github

# （在 Claude Code 内）检查服务器状态
/mcp

/mcp 面板在每个已连接服务器旁边显示工具数量，并标记声明 tools 能力但未公开任何工具的服务器。

如果你的请求需要仍在后台连接的服务器的工具，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 自动以指数退避重新连接：最多五次尝试，从一秒延迟开始，每次翻倍。在重连期间，服务器在 /mcp 中显示为待处理。五次失败尝试后，服务器标记为失败，你可以从 /mcp 手动重试。Stdio 服务器是本地进程，不会自动重连。

当 HTTP 或 SSE 服务器在启动时首次连接失败时，相同的退避策略适用。自 v2.1.121 起，Claude Code 在瞬态错误（如 5xx 响应、连接被拒绝或超时）上重试初始连接最多三次，然后在仍无法连接时将服务器标记为失败。身份验证和未找到错误不会重试，因为它们需要配置更改才能解决。

使用通道推送消息

MCP 服务器还可以直接将消息推送到你的会话中，以便 Claude 可以响应 CI 结果、监控警报或聊天消息等外部事件。要启用此功能，你的服务器声明 claude/channel 能力，你在启动时使用 --channels 标志选择加入。参见通道使用官方支持的通道，或通道参考构建自己的通道。

Tip

提示：

使用 --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 的值会被提升为一秒。对于 HTTP 和 SSE 服务器，每请求的 fetch 首字节预算有 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 服务器
环境变量：使用 {{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT} 访问捆绑的插件文件，{{CONTENT}}amp;#123;CLAUDE_PLUGIN_DATA} 访问持久状态（在插件更新后保留），{{CONTENT}}amp;#123;CLAUDE_PROJECT_DIR} 访问稳定的项目根目录
用户环境访问：访问与手动配置的服务器相同的环境变量
多种传输类型：支持 stdio、SSE 和 HTTP 传输（传输支持可能因服务器而异）

查看插件 MCP 服务器：

# 在 Claude Code 内，查看所有 MCP 服务器包括插件服务器
/mcp

插件服务器在列表中显示带有指示器，表明它们来自插件。

插件 MCP 服务器的优势：

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

参见插件组件参考了解将 MCP 服务器与插件捆绑的详情。

MCP 安装范围

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

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

本地范围

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

Note

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 在使用 .mcp.json 文件中的项目范围服务器之前会提示批准。如果你需要重置这些批准选择，使用 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 或命令的被视为重复。

`.mcp.json` 中的环境变量扩展

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

支持的语法：

{{CONTENT}}amp;#123;VAR} - 扩展为环境变量 VAR 的值
${VAR:-default} - 如果已设置则扩展为 VAR，否则使用 default

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

command - 服务器可执行文件路径
args - 命令行参数
env - 传递给服务器的环境变量
url - 用于 HTTP 服务器类型
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

使用你的 Sentry 帐户进行身份验证：

/mcp

然后调试生产问题：

What are the most common errors in the last 24 hours?

Show me the stack trace for error ID abc123

Which deployment introduced these new errors?

示例：连接到 GitHub 进行代码审查

GitHub 的远程 MCP 服务器使用作为请求头传递的 GitHub 个人访问令牌进行身份验证。要获取一个，打开你的 GitHub 令牌设置，生成一个新的细粒度令牌，授予对你希望 Claude 工作的仓库的访问权限，然后添加服务器：

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

然后使用 GitHub：

Review PR #456 and suggest improvements

Create a new issue for the bug we just found

Show me all open PRs assigned to me

示例：查询 PostgreSQL 数据库

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

然后自然地查询你的数据库：

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

对远程 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 命令
在 Claude Code 中，使用命令：
```
/mcp
```
然后按照浏览器中的步骤登录。

Tip

提示：

身份验证令牌安全存储并自动刷新
使用 /mcp 菜单中的"Clear authentication"撤销访问权限
如果浏览器未自动打开，复制提供的 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 元数据文档（CIMD）代替动态客户端注册的服务器，并自动发现这些。如果自动发现失败，先通过服务器的开发者门户注册 OAuth 应用，然后在添加服务器时提供凭据。

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

使用凭据添加服务器

选择以下方法之一。用于 --callback-port 的端口可以是任何可用端口。只需匹配你在上一步中注册的重定向 URI。

使用 --client-id 传递应用的客户端 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

在 JSON 配置中包含 oauth 对象，并将 --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

使用不带客户端 ID 的 --callback-port 在使用动态客户端注册时固定端口：

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

通过环境变量设置密钥以跳过交互提示：

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

在 Claude Code 中进行身份验证
在 Claude Code 中运行 /mcp 并按照浏览器登录流程操作。

Tip

提示：

客户端密钥安全存储在你的系统钥匙串（macOS）或凭据文件中，而不是配置中
如果服务器使用没有密钥的公共 OAuth 客户端，仅使用 --client-id 而不带 --client-secret
--callback-port 可以与 --client-id 一起使用或单独使用
这些标志仅适用于 HTTP 和 SSE 传输。对 stdio 服务器无效
使用 claude mcp get <name> 验证服务器是否配置了 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 使用相同的固定范围重新进行身份验证。当你需要的工具需要固定范围之外的范围时，扩大 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 服务器服务的单一助手脚本。

Note

headersHelper 执行任意 shell 命令。在项目或本地范围定义时，仅在接受工作区信任对话后运行。

从 JSON 配置添加 MCP 服务器

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

从 JSON 添加 MCP 服务器

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

# 示例：使用 JSON 配置添加 HTTP 服务器
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 示例：使用 JSON 配置添加 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
```

Tip

提示：

确保 JSON 在你的 shell 中正确转义
JSON 必须符合 MCP 服务器配置模式
你可以使用 --scope user 将服务器添加到用户配置而不是项目特定配置

从 Claude Desktop 导入 MCP 服务器

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

从 Claude Desktop 导入服务器

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

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

Tip

提示：

此功能仅在 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 中配置 MCP 服务器
在 claude.ai/customize/connectors 添加服务器。在 Team 和 Enterprise 计划中，只有管理员可以添加服务器。
对 MCP 服务器进行身份验证
在 Claude.ai 中完成任何必需的身份验证步骤。
在 Claude Code 中查看和管理服务器
在 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 中使用此功能，通过将以下配置添加到 claude_desktop_config.json：

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

Warning

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

要查找完整路径：

which claude

然后在配置中使用完整路径：

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

没有正确的可执行文件路径，你会遇到类似 spawn claude ENOENT 的错误。

Tip

提示：

服务器提供对 Claude 工具的访问，如 View、Edit、LS 等。
在 Claude Desktop 中，尝试让 Claude 读取目录中的文件、进行编辑等。
请注意，此 MCP 服务器仅将 Claude Code 的工具暴露给你的 MCP 客户端，因此你自己的客户端负责为单个工具调用实现用户确认。

MCP 输出限制和警告

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

输出警告阈值：当任何 MCP 工具输出超过 10,000 个 token 时，Claude Code 显示警告
可配置限制：你可以使用 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 限制。

Warning

如果你经常遇到特定 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 引用资源：

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

多个资源引用

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

Compare @postgres:schema://users with @docs:file://database/user-model

Tip

提示：

资源在被引用时自动获取并作为附件包含
资源路径在 @ 提及自动补全中支持模糊搜索
当服务器支持时，Claude Code 自动提供列出和读取 MCP 资源的工具
资源可以包含 MCP 服务器提供的任何类型的内容（文本、JSON、结构化数据等）

使用 MCP 工具搜索进行扩展

工具搜索通过延迟工具定义直到 Claude 需要它们来保持 MCP 上下文使用量低。会话启动时仅加载工具名称，因此添加更多 MCP 服务器对上下文窗口的影响最小。

工作原理

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

如果你更喜欢基于阈值的加载，设置 ENABLE_TOOL_SEARCH=auto 在工具适合上下文窗口的 10% 时预先加载模式，仅延迟溢出部分。参见配置工具搜索了解所有选项。

对于 MCP 服务器作者

如果你正在构建 MCP 服务器，启用工具搜索后服务器说明字段变得更加有用。服务器说明帮助 Claude 了解何时搜索你的工具，类似于技能的工作方式。

添加清晰、描述性的服务器说明，解释：

你的工具处理什么类别的任务
Claude 何时应该搜索你的工具
你的服务器提供的关键能力

Claude Code 在 2KB 处截断工具描述和服务器说明。保持简洁以避免截断，并将关键细节放在开头附近。

配置工具搜索

工具搜索默认启用：MCP 工具被延迟并按需发现。Claude Code 在 Vertex AI 上默认禁用它。当 ANTHROPIC_BASE_URL 指向非第一方主机时也会禁用，因为大多数代理不转发 tool_reference 块。明确设置 ENABLE_TOOL_SEARCH 以覆盖任一回退。

工具搜索需要支持 tool_reference 块的模型：Sonnet 4 及更高版本，或 Opus 4 及更高版本。Haiku 模型不支持。在 Vertex AI 上，工具搜索支持 Claude Sonnet 4.5 及更高版本和 Claude Opus 4.5 及更高版本。

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

值	行为
（未设置）	所有 MCP 工具延迟并按需加载。在 Vertex AI 或 `ANTHROPIC_BASE_URL` 为非第一方主机时回退到预先加载
`true`	所有 MCP 工具延迟。Claude Code 即使在 Vertex AI 上和通过代理也发送 beta 头。在早于 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 服务器可以公开在 Claude Code 中作为命令可用的提示。

执行 MCP 提示

发现可用提示
输入 / 查看所有可用命令，包括来自 MCP 服务器的命令。MCP 提示以 /mcp__servername__promptname 格式出现。
执行不带参数的提示
```
/mcp__github__list_prs
```
执行带参数的提示
许多提示接受参数。在命令后以空格分隔传递：
```
/mcp__github__pr_review 456
```
```
/mcp__jira__create_issue "Bug in login flow" high
```

Tip

提示：

MCP 提示从已连接的服务器动态发现
参数根据提示定义的参数解析
提示结果直接注入对话中
服务器和提示名称被标准化（空格变为下划线）

托管 MCP 配置

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

文档索引

通过 MCP 将 Claude Code 连接到工具

使用 MCP 可以做什么

查找和构建 MCP 服务器

安装插件

运行构建技能

安装 MCP 服务器

选项 1：添加远程 HTTP 服务器

选项 2：添加远程 SSE 服务器

选项 3：添加本地 stdio 服务器

管理你的服务器

动态工具更新

自动重连

使用通道推送消息

插件提供的 MCP 服务器

MCP 安装范围

本地范围

项目范围

用户范围

范围层次和优先级

.mcp.json 中的环境变量扩展

实际示例

示例：使用 Sentry 监控错误

示例：连接到 GitHub 进行代码审查

示例：查询 PostgreSQL 数据库

对远程 MCP 服务器进行身份验证

添加需要身份验证的服务器

在 Claude Code 中使用 /mcp 命令

使用固定的 OAuth 回调端口

使用预配置的 OAuth 凭据

向服务器注册 OAuth 应用

使用凭据添加服务器

在 Claude Code 中进行身份验证

覆盖 OAuth 元数据发现

限制 OAuth 范围

使用动态头进行自定义身份验证

从 JSON 配置添加 MCP 服务器

从 JSON 添加 MCP 服务器

验证服务器已添加

从 Claude Desktop 导入 MCP 服务器

从 Claude Desktop 导入服务器

选择要导入的服务器

验证服务器已导入

使用来自 Claude.ai 的 MCP 服务器

在 Claude.ai 中配置 MCP 服务器

对 MCP 服务器进行身份验证

在 Claude Code 中查看和管理服务器

将 Claude Code 用作 MCP 服务器

MCP 输出限制和警告

为特定工具提高限制

响应 MCP 引导请求

使用 MCP 资源

引用 MCP 资源

列出可用资源

引用特定资源

多个资源引用

使用 MCP 工具搜索进行扩展

工作原理

对于 MCP 服务器作者

配置工具搜索

将服务器从延迟中豁免

使用 MCP 提示作为命令

执行 MCP 提示

发现可用提示

执行不带参数的提示

执行带参数的提示

托管 MCP 配置

`.mcp.json` 中的环境变量扩展