Claude Code 虽能完成代码编写、文件操作等任务，但在浏览器自动化、数据库查询、GitHub 操作等场景中，还需要借助外部工具扩展能力。MCP（Model Context Protocol）正是连接 Claude Code 与外部工具的协议。本文将介绍 MCP 作用、Server 选择、3 种配置方法及常见报错排查。
一、Claude Code 为什么需要 MCP？
MCP（Model Context Protocol）是一套连接 AI 应用、外部工具和数据源的开放协议。Claude Code 本身可以完成代码编写、文件处理等任务，而通过 MCP，可以进一步接入浏览器、数据库、代码仓库等外部能力。
从工作原理来看，Claude Code 负责理解用户需求并判断是否需要调用外部工具，MCP Server 则负责提供具体能力。收到调用请求后，Server 执行对应操作，再将结果返回给 Claude Code。通过这种方式，不同工具可以按照统一的协议接入，无需为每个工具单独建立连接机制。
目前 MCP 常见的传输协议主要有两种：
- stdio：通过标准输入输出进行通信，通常用于本地运行的 MCP Server
- HTTP：通过 HTTP 与远程 MCP Server 通信，适合已经部署在服务器上的服务
了解完MCP的传输协议后，选择MCP Server可以根据实际提供的能力进行区分：
| 类型 | 主要用途 | 常见场景 |
| 浏览器自动化 | 控制浏览器 | 网页访问、测试、自动化 |
| 文件与本地资源 | 处理指定资源 | 文件处理、资料读取 |
| 开发工具 | 连接开发服务 | GitHub、Issue、代码协作 |
| 数据查询 | 连接数据服务 | 数据查询、分析、检索 |
因此，选择 MCP 时不必盲目追求数量，先明确需要扩展的能力，再根据 Server 的功能和运行环境进行选择即可。
二、Claude Code 配置 MCP 的 3 种常用方法
方法一：命令行添加 HTTP MCP Server
HTTP MCP Server 通常已经部署在远程环境中，Claude Code 只需要连接对应的服务地址即可，不需要在本地安装和启动 Server。对于新手来说，这种方式配置步骤较少，适合快速接入已经搭建好的 MCP 服务。
在 Claude Code 中执行的基本命令如下：
claude mcp add --transport http <名称> <MCP服务URL>
如果服务需要身份认证，可以使用 --header 添加 Token：
claude mcp add --transport http my-server https://example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"
添加完成后，在 Claude Code 中输入 /mcp，检查 Server 是否出现在列表中并确认连接状态。如果没有连接成功，建议按照 MCP 地址、认证信息、网络连接、远程 Server 状态的顺序检查。先确认服务地址本身可以正常访问，再排查 Claude Code 的配置问题，可以避免反复修改命令。
方法二：命令行添加 stdio MCP Server
如果 MCP Server 需要在本地运行，可以使用 stdio 方式。Claude Code 会启动对应程序，并通过标准输入输出与 Server 通信，因此 npx、uvx、Node.js 和 Python 等本地工具都可以采用这种方式。
先按照下面的格式添加 Server：
claude mcp add --transport stdio <名称> -- <启动命令> [参数]
这里的 -- 用于区分 Claude Code 自身的参数和 MCP Server 的启动参数。配置时需要确保启动命令已经安装，并且能够在当前终端环境中正常执行。
以 Playwright MCP 为例，可以直接执行：
claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest
配置完成后，可以通过 /mcp 检查 Server 是否正常连接。如果像将Playwright MCP这类浏览器自动化工具进一步用于数据采集，真正需要关注的不只是浏览器能否打开网页，还包括目标站点的反爬机制。
网站通常会结合请求频率、访问行为、Cookie 和会话状态、浏览器特征和网络出口等判断访问是否异常，可能出现验证码、访问受限、页面加载失败等情况，这些限制会直接影响采集效率和数据完整性，更严重可能会导致账号被封。
对于需要通过自动化数据采集的场景下，可以在浏览器或运行环境中配置像IPFoxy的住宅代理，相对于数据中心代理，这类代理更接近正是用户网络的出口特征，适合长期稳定的采集任务，能够减少网络出口频繁变化造成的任务中断/访问异常，降低触发反爬机制的概率。
方法三：通过 JSON 配置 MCP Server
如果需要同时管理多个 MCP Server，或者希望将配置纳入项目协作，可以直接通过 JSON 文件进行管理。
Claude Code 主要有两种配置范围：项目级 .mcp.json 和用户级 ~/.claude.json。其中，.mcp.json 适合团队协作，配置可以随项目统一维护；~/.claude.json 更适合个人使用，可以在不同项目中复用自己的 MCP 配置。
以下为项目级 .mcp.json 配置示例：
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
如果只希望个人全局使用，可以在 ~/.claude.json 中配置：
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
两种配置的区别主要在作用范围：项目级配置适合团队统一工具和环境，用户级配置则适合个人长期使用。无论采用哪种方式，完成配置后都可以通过 /mcp 检查 Server 是否被 Claude Code 正确识别。
三、Claude Code 配置 MCP 失败：常见问题及解决方法
1. MCP 连接 502 或超时
这类问题主要出现在 HTTP MCP 连接过程中，常见原因包括 MCP 地址错误、远程 Server 异常、认证信息失效，以及本地网络无法正常访问目标服务。
可以按以下顺序检查：
- 确认 MCP URL 是否填写正确，并尝试在浏览器或终端访问
- 检查 Token、Header 等认证信息是否有效
- 确认远程 MCP Server 当前是否正常运行
- 排除本地网络、防火墙或代理导致的连接问题
如果目标 MCP 是远程 HTTP 服务，而当前环境需要通过 stdio 连接，可以使用 mcp-remote 作为桥接层，将本地 stdio 请求转发到远程 MCP。但如果远程服务本身返回 502，仍需要从服务端处理。
2. Windows 下出现 npx ENOENT
ENOENT 通常表示系统找不到指定的可执行文件。Windows 下 Claude Code 调用 npx 时，如果 Node.js 未正确安装、PATH 未配置，或者 Shell 没有获取到正确的环境变量，就可能出现该错误。
先在终端执行：
npx --version
如果无法运行，重新检查 Node.js、npm 安装及 PATH 配置；如果终端能够正常运行，但 Claude Code 仍报错，则检查 Claude Code 使用的 Shell 和环境变量。必要时，可以改用 node 直接启动 MCP Server，绕过 npx 调用。
3. 出现 uvx ENOENT
与 npx ENOENT 类似，该错误通常意味着 Claude Code 找不到 uvx 可执行文件，常见原因是 uv 未安装，或者安装目录没有加入系统 PATH。
先执行：
uvx --version
如果命令不存在，安装 uv 并将其目录加入 PATH。修改环境变量后重新打开终端并重启 Claude Code，再检查 MCP 是否能够正常启动。
4. 显示 No MCP servers configured
该提示通常意味着 Claude Code 没有读取到有效的 MCP Server 配置，而不是 Server 连接失败。常见原因包括 Server 没有成功添加、配置文件位置错误或 JSON 格式存在问题。
先确认 MCP Server 是否已经添加，再检查 .mcp.json 或 ~/.claude.json 是否位于正确位置，并核对 mcpServers、type、command、args 等字段。修改后重新启动 Claude Code，并运行 /mcp 查看 Server 状态。
如果是 Windows + Playwright MCP，还应重点检查 npx、Shell 和 stdio 通信。如果 npx 可以正常运行但 Server 仍无法启动，可以尝试使用 Node.js 直接执行 Playwright MCP 的入口文件。
四、FAQ
Claude Code 怎么查看 MCP 是否配置成功？
进入 Claude Code 后运行 /mcp，可以查看已经配置的 MCP Server 及其连接状态。
Claude Code 可以同时配置多个 MCP Server 吗？
可以。Claude Code 支持配置多个 MCP Server，不同 Server 可以提供不同的工具能力。实际使用时建议按照任务需求选择，避免配置过多无关工具增加管理成本。
MCP Server 配置后为什么 Claude Code 还是无法调用？
除了连接状态外，还需要检查 Server 是否实际提供了对应工具，以及工具依赖是否安装完整。可以先通过 /mcp 确认连接，再检查 Server 的启动命令、运行环境和具体工具权限。
五、总结
Claude Code 配置 MCP 的核心并不在于记住命令，而在于根据 Server 的运行方式选择合适的配置方案。远程服务优先使用 HTTP，本地工具使用 stdio，个人长期使用或团队协作则可以通过 JSON 文件管理配置。
遇到运行异常时，按照配置、依赖、Shell 环境、网络连接和 Server 状态的顺序逐项排查，能够更快定位问题并完成修复。
