连接到 MCP 服务器

为 Claude Code 添加一个 MCP 服务器，验证连接，并找到磁盘上的配置文件。

模型上下文协议（Model Context Protocol，MCP）让 Claude Code 能使用其内置工具集之外的工具，例如搜索一个问题跟踪系统、查询数据库，或操控一个网页浏览器。这些工具来自 MCP 服务器，它们运行在你的机器上，或作为托管服务运行。

本指南将带你完成用 Claude Code CLI 连接一个 MCP 服务器的完整流程。读完之后，你会拥有一个已连接并能响应的服务器，知道其配置在磁盘上的位置，并知道如何修复最常见的连接错误。

关于在 Claude Code 中连接和配置 MCP 服务器的所有方式，请参阅MCP 参考文档。

开始之前

请确保你具备：

• 已安装 Claude Code并完成身份验证
• 一个在项目目录下打开的终端。任何目录都可以，包括空目录。

添加并验证一个服务器

以下示例会连接到Claude Code 文档 MCP 服务器，这是一个提供 Claude Code 文档全文搜索的托管服务器。它不需要身份验证或任何特殊配置，因此非常适合用来测试整套搭建流程。

对任何服务器，步骤都是一样的：添加它，检查连接状态，然后在会话中使用它，最后可选地进行清理。有些服务器会多出一步，例如浏览器登录，见更多 MCP 服务器示例。要查找更多可连接的服务器，请浏览 Anthropic 目录。

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

claude mcp list

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

claude mcp remove claude-code-docs

服务器保存位置

claude mcp add 命令会把服务器的详细信息写入一个配置文件。默认情况下，它会以 local 范围注册该服务器：只对你私有，只在当前项目中生效。传入 --scope user 可为你所有的项目一次性注册它，传入 --scope project 可与团队成员共享。更改服务器范围会详细介绍这两种方式。

添加服务器还有其他方式，本页后面会分别介绍：

• 添加本地服务器：在你的机器上运行一个程序，而不是连接到某个网址。
• 直接编辑 .mcp.json：自己编写 JSON 条目，而不是使用命令。
• 连接需要登录的服务器：添加一个需要浏览器登录才能使用其工具的托管服务器。

在磁盘上找到你的配置

根据 --scope 标志，claude mcp add 命令会将服务器写入三种范围之一，存储在两个文件中。你不需要直接编辑这些文件，但知道它们的位置有助于调试和版本控制。

在 Windows 上，~/.claude.json 会解析为 %USERPROFILE%\.claude.json，通常是 C:\Users\YourName\.claude.json。如果你设置了 CLAUDE_CONFIG_DIR，Claude Code 会改为从该目录内读取 .claude.json。

运行 claude mcp get claude-code-docs 可查看某个服务器的定义保存在哪个范围内。关于同一个服务器在多个范围中都有定义时这些范围如何相互作用，请参阅MCP 安装范围。

更改服务器范围

一个服务器的范围在你添加它时就固定了，因此要更改范围，意味着要先移除该条目，再以新的范围重新添加。以下两种情况都从移除第一个教程中的本地条目开始，这样该服务器就只有一个定义。如果你已经在那个教程结尾移除过它，可以跳过这条命令：

claude mcp remove claude-code-docs --scope local

在你所有的项目中使用某个服务器

以 user 范围重新添加该服务器，使其在你打开的每个项目中都生效，同时仍只对你私有：

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

与你的团队共享某个服务器

以 project 范围重新添加该服务器，这会写入项目根目录下的 .mcp.json：

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

将 .mcp.json 提交到版本控制。克隆该仓库并启动 Claude Code 的团队成员会看到一个批准该服务器的提示，批准后该服务器同样会为他们连接。

更多 MCP 服务器示例

第一个教程使用的是一个无需任何登录即可连接的托管服务器。以下示例涵盖另外两种常见形态，流程同样是添加、检查、使用。

添加一个本地服务器

一个本地 stdio 服务器是 Claude Code 在你机器上作为子进程启动的程序，而不是通过网址访问的服务。当某个工具需要访问本地资源（例如浏览器、你的文件系统，或数据库套接字）时，可以使用这种方式。

Playwright MCP 服务器是一个不错的尝试对象：它给 Claude 提供了一个可以导航、点击和读取内容的浏览器，且无需任何账号。它通过 npx 运行，因此需要 Node.js 18 或更高版本。

claude mcp add playwright -- npx -y @playwright/mcp@latest

claude mcp list

Use playwright to open https://example.com and tell me the page title

连接需要登录的服务器

像 Sentry、Linear 和 Notion 这类托管服务，会在 OAuth 之后运行它们的 MCP 服务器：你先添加该服务器的网址，然后通过浏览器登录。

以下步骤以 Sentry 为示例。要连接其他服务，请替换成它的网址，你可以在 Anthropic 目录或该服务的文档中找到。

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

/mcp

用静态令牌而非 OAuth 进行身份验证的服务器，可以在添加时用 --header "Authorization: Bearer <token>" 传入令牌。具体示例请参阅 GitHub 示例。

直接编辑 .mcp.json

范围表中的每个文件对服务器条目都使用相同的 JSON 格式。本节编辑 .mcp.json，即项目范围的文件。这是最值得手动编写的一个，因为它会被纳入仓库，为你的团队起到“配置即代码”的作用。

在你的项目根目录创建 .mcp.json。以下示例定义了本指南中的两个服务器：通过 HTTP 访问的托管文档服务器，以及作为本地 stdio 进程的 Playwright 服务器：

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

字段会因服务器类型而不同：

• 对于 HTTP 服务器，url 是 Claude Code 连接的端点。
• 对于 stdio 服务器，command 和 args 是它运行的程序。

保存该文件后，在该项目中启动一个新的 Claude Code 会话。Claude Code 会在启动时读取 .mcp.json。

Claude Code 第一次看到某个项目范围的服务器时，会请你批准。这个提示的存在，是为了防止你克隆的某个仓库在未经你同意的情况下在你机器上启动进程。批准该提示，或如果你错过了，可以之后运行 /mcp 补批。

批准之后，运行 /mcp 并检查这些服务器是否显示为已连接。如果某个显示为错误，请参阅故障排查。

从其他界面连接

本指南使用的是 claude mcp CLI 命令，但 Claude Code 的每个界面都可以连接 MCP 服务器：

• Claude Code 桌面应用：通过连接器界面添加服务器。
• Claude Desktop 聊天应用：这是与 Claude Code 分离的另一个应用。要把其 claude_desktop_config.json 中的服务器复制到 CLI 中，可在 macOS 或 WSL 上运行 claude mcp add-from-claude-desktop。
• VS Code：请参阅通过 MCP 连接外部工具。
• 网页版 Claude Code：会从你的仓库读取 .mcp.json。请参阅直接编辑 .mcp.json。
• Claude.ai：你在 claude.ai/customize/connectors 添加的连接器，会在你用该账号登录时自动加载到 CLI 中。请参阅从 Claude.ai 使用 MCP 服务器。

故障排查

如果某个服务器无法连接，可在会话内用 /mcp，或在 shell 中用 claude mcp list 检查其状态，然后对照以下症状排查。/mcp 面板也可以让你在不离开会话的情况下重新连接或进行身份验证。

curl -I https://mcp.sentry.dev/mcp

npx -y @playwright/mcp@latest

MCP_TIMEOUT=60000 claude

$env:MCP_TIMEOUT = "60000"; claude

claude mcp remove claude-code-docs

claude mcp reset-project-choices

后续步骤

连接好一个服务器之后，可以探索 MCP 提供的其他能力：

• 在 Anthropic 目录中查找更多 MCP 服务器
• 使用安装范围与你的团队共享服务器
• 用统一管理设置和策略控制为组织管理 MCP 访问权限
• 用 @ 提及在提示词中引用 MCP 资源
• 从 / 菜单将 MCP 提示词作为命令运行
• 用 MCP SDK 构建你自己的服务器