连接到 MCP 服务器

将 MCP 服务器添加到 Claude Code，验证连接，并在磁盘上找到配置。

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 以与队友共享。更改服务器范围 介绍了两者。

还有其他方式添加服务器，每种都在本页后面介绍：

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

在磁盘上找到您的配置

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

在 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 在您的机器上作为子进程启动的程序，而不是它通过 URL 访问的服务。对于需要访问本地资源（如浏览器、您的文件系统或数据库套接字）的工具，请使用一个。

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 服务器：您添加服务器的 URL，然后通过浏览器登录。

下面的步骤以 Sentry 为例。要连接不同的服务，请替换其 URL，您可以在 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 桌面应用：通过 连接器 UI 添加服务器。
• Claude 桌面聊天应用：与 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 面板还允许您重新连接或进行身份验证而无需离开会话。

* 您从不同的项目运行了 `claude mcp add`。本地范围的服务器与您添加它们的项目相关联：存储库根目录，或如果您不在 git 存储库中，则为确切目录。从您现在所在的项目重新添加服务器，或使用 `--scope user` 添加它，以便它不与项目相关联。
* 您在错误的路径编辑了配置文件。正确的文件是 `~/.claude.json` 和 `<project>/.mcp.json`。Claude Code 不读取 `~/.claude/config/mcp.json`、`~/.claude/mcp.json` 或 `%APPDATA%\Claude\mcp.json` 等路径。

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 启用的其余功能：

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