快速入门

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 安装范围

https://code.claude.com/docs/zh-CN/mcp#mcp-installation-scopes

在 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 的队友会看到批准服务器的提示，然后它也会为他们连接

本地 stdio 服务器是 Claude Code 在机器上作为子进程启动的程序，而不是它通过 URL 访问的服务

对于需要访问本地资源（如浏览器、您的文件系统或数据库套接字）的工具，请使用一个

Playwright MCP 服务器 是一个很好的尝试：它为 Claude 提供了一个可以导航、点击和读取的浏览器，并且不需要帐户

它通过 npx 运行，因此需要 Node.js 18 或更高版本

1. 添加 Playwright 服务器，使用 Claude Code 应该运行以启动它的命令注册服务器：

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

   此命令与托管示例的不同之处有三个：

   • 没有 –transport 标志，因为本地服务器使用默认的 stdio 传输
   • – 分隔符之后的所有内容都是 Claude Code 运行以启动服务器的命令

   • -y 告诉 npx 安装包而不提示

     Playwright 驱动机器上已安装的任何 Chrome
     
     要使用不同的浏览器，请在 @playwright/mcp@latest 之后附加 --browser 和浏览器名称，例如 --browser firefox
     

2. 检查连接，Added 确认意味着条目已保存，而不是命令运行。检查连接：

   claude mcp list
   

   第一次检查可能会在 npx 下载包时显示 ✗ Failed to connect，因此请稍等片刻并再次运行
   

3. 使用浏览器，给 Claude 一个需要浏览器的任务：

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

   浏览器窗口打开，以便可以观看它工作，Claude 输出中的工具调用标有 playwright 服务器名称和操作，如 browser_navigate

   尝试将其指向本地开发服务器以检查页面在更改后是否仍然呈现，或让它逐步完成错误报告
   

托管服务（如 Sentry、Linear 和 Notion）在 OAuth 后面运行其 MCP 服务器

添加服务器的 URL，然后通过浏览器登录

下面的步骤以 Sentry 为例。要连接不同的服务，请替换其 URL，可以在 Anthropic 目录 或服务的文档中找到：

1. 添加服务器，add 命令与文档服务器相同，使用 Sentry 的 URL：

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

   添加后，claude mcp list 显示服务器为 ! Needs authentication
   
   这是预期的：下一步完成登录
   

2. 在浏览器中进行身份验证，启动 Claude Code 会话并打开 MCP 面板：

   /mcp
   

   1. 从列表中选择 sentry，按 Enter
   2. 然后选择 Authenticate

   3. 浏览器打开到 Sentry 的登录页面。在那里批准连接

      回到 Claude Code，服务器的状态更改为已连接
      
      如果登录失败或浏览器没有打开，请参阅故障排除
      
      https://code.claude.com/docs/zh-CN/mcp-quickstart#troubleshooting
      

3. 使用服务器，询问 Claude 需要该服务的内容

   询问 Claude 需要该服务的内容，例如 What Sentry projects do I have access to?
   
   并查找在其输出中标有 sentry 服务器名称的工具调用
   

使用静态令牌而不是 OAuth 进行身份验证的服务器在添加时使用 –header "Authorization: Bearer <token>" 获取令牌

Claude Code 没有为当前目录找到任何服务器。最常见的原因：

• 从不同的项目运行了 claude mcp add。本地范围的服务器与您添加它们的项目相关联：存储库根目录，或如果不在 git 存储库中，则为确切目录

  从现在所在的项目重新添加服务器，或使用 --scope user 添加它，以便它不与项目相关联
  

• 在错误的路径编辑了配置文件。正确的文件是 ~/.claude.json 和 <project>/.mcp.json
  • Claude Code 不读取 ~/.claude/.mcp.json、~/.claude/config/mcp.json、~/.claude/mcp.json 或 %APPDATA%\Claude\mcp.json 等路径
  • 对于用户范围的服务器，运行 claude mcp add –scope user，它会写入 ~/.claude.json 中的 mcpServers 密钥
  • 对于项目范围的服务器，编辑项目根目录中的 .mcp.json

两种状态都意味着服务器没有启动或 URL 没有响应。对于期望令牌而不是连接需要登录的服务器中涵盖的浏览器登录的 HTTP 服务器，它们也可能出现 从 v2.1.191 开始，返回 404 Not Found 的 HTTP 服务器在 /mcp 中选择服务器时显示 MCP endpoint not found at <url>. Check the URL in your MCP config.，并显示 Claude Code 尝试的 URL。早期版本显示通用的 Error POSTing to endpoint 消息，不包含 URL

将 URL 与服务器的文档化 MCP 端点路径进行比较，然后运行 claude mcp remove <name> 并使用正确的 URL 重新添加

对于 HTTP 服务器，确认 URL 可从本地机器访问：

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

在 PowerShell 中，使用 curl.exe 而不是 curl，以便请求转到真实的 curl 二进制文件而不是 Invoke-WebRequest 别名

响应告诉您您有什么样的问题：

• 404 或 405：服务器已启动。许多 MCP 端点仅回答 POST 请求，因此这仍然确认 URL 可从您的机器访问

• 401 或 403：服务器已启动，需要进行身份验证。使用连接需要登录的服务器中的浏览器登录，或对于接受令牌的服务器（如 GitHub 的）

  在 claude mcp add 命令上使用 --header "Authorization: Bearer <token>" 传递它
  

• 完全没有响应：检查 URL 和您的网络

对于 stdio 服务器，直接在终端中运行配置的命令以查看基础错误。对于本指南中的 Playwright 服务器，运行：

npx -y @playwright/mcp@latest

接下来发生的事情告诉问题在哪里：

• 命令启动并等待输入：服务器本身工作。运行 claude mcp get <name> 并确认那里显示的命令与您刚刚运行的命令匹配

  • 如果显示的命令与键入的不同，可能在服务器命令之前省略了 – 分隔符

    删除服务器并使用 -- 重新添加它
    

  • 如果手工编写了 .mcp.json，请检查其语法和位置

• 命令出错：消息命名缺少的内容

  例如 Node.js 或浏览器
  

服务器花费的时间超过了默认的 30 秒启动超时。stdio 服务器的第一次运行在 npx 下载包时可能很慢。使用 MCP_TIMEOUT 环境变量（以毫秒为单位）增加限制：

MCP_TIMEOUT=60000 claude

在 PowerShell 中，在同一行上的命令之前设置变量：

$env:MCP_TIMEOUT = "60000"; claude

已在同一范围内添加了具有该名称的服务器。要么先删除现有条目，要么选择不同的名称：

claude mcp remove claude-code-docs

如果名称存在于多个范围内，remove 报告 exists in multiple scopes。传递 –scope 以选择要删除的副本

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

在会话内运行 /mcp 并选择服务器以查看其工具列表。如果列表为空，服务器启动但没有注册任何工具

这通常意味着它缺少必需的环境变量，例如 API 密钥

在 claude mcp add 上使用 –env KEY=value 传递变量，或在服务器的 .mcp.json 条目的 env 字段中传递

服务器的文档列出了它需要的变量

Claude Code 在会话启动时读取 .mcp.json。编辑文件后退出并重新启动会话

如果服务器仍然没有出现，运行 /mcp 并查找解析警告

Claude Code 跳过格式错误的条目并在那里显示有问题的字段

如果之前在提示时拒绝了服务器，请重置项目批准：

claude mcp reset-project-choices

运行 /mcp，选择服务器，然后再次选择 Authenticate。如果浏览器没有自动打开，复制终端中显示的 URL 并手动打开它

有关固定回调端口和预配置凭据，请参阅使用远程 MCP 服务器进行身份验证

https://code.claude.com/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers