Claude Code MCP 集成：实现工具与 Agent 的连接

上次更新: June 28, 2026

开箱即用，Claude Code 可以读取和编辑文件并运行 shell 命令。但它无法读取你的 GitHub issues、查询你的数据库或驱动浏览器。Model Context Protocol (MCP) 弥补了这一差距：它是允许 agent 与外部工具和数据通信的标准插头。本指南将展示精确的 claude mcp add 命令，说明何时选择本地还是远程服务器，如何工作作用域（scopes），哪些服务器值得连接，以及在信任任何服务器之前需要运行的安全检查。

快速答案：如何将 MCP 服务器添加到 Claude Code？

你使用 claude mcp add 命令注册一个服务器，然后 Claude Code 在会话期间可以调用其工具。

对于作为进程在你的机器上运行的本地服务器：

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

对于通过 HTTPS 访问的远程服务器：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

添加服务器后，在 Claude Code 中运行 /mcp 查看其连接状态并完成任何 OAuth 登录。使用 claude mcp list 来确认注册情况。官方命令参考可以在 Claude Code MCP 文档 获取。

什么是 MCP，为什么要将其连接到 Claude Code？

MCP 是一个开放协议，最初由 Anthropic 发布，它定义了 AI 客户端和工具服务器如何交换能力。一个服务器会宣传其 工具（agent 可以执行的操作）、资源（它可以读取的数据）和 提示词。任何支持 MCP 的客户端都可以使用任何 MCP 服务器，因此一个 GitHub 服务器可以在 Claude Code、IDE 或其他 agent 中工作，无需自定义粘合剂。规范和服务器注册表位于 modelcontextprotocol.io。

实际益处是：你不再需要将 issue 内容粘贴到聊天中，只需连接一次 GitHub 服务器，然后让 agent 直接读取、标记和回复 issues。有关协议本身的更深入背景信息，请参阅我们的 MCP 解释器，而要了解完整的工具上下文，请阅读 Claude Code终极指南。

一个服务器可以是你编写的微小 stdio 脚本、Docker 镜像，或供应商托管的 SaaS 端点。一旦它们遵循 MCP 标准，Claude Code 会将它们视为相同的方式对待。

你应该使用哪种传输方式：本地还是远程？

传输（Transport）指的是 Claude Code 如何到达服务器。本地服务器在你的机器上通过 stdio 运行；远程服务器则在别处运行，并通过 HTTP 或 SSE 回应。选择通常取决于数据存储的位置。

当工具需要本地文件或服务时，使用本地 stdio 服务器，例如项目资产文件夹或运行在 localhost 上的 Postgres 实例。当供应商已经托管了服务器时，使用远程 HTTP 或 SSE 服务器，因为这样可以跳过安装步骤，并且无需触碰你的配置即可获得更新。远程服务器几乎总是通过 OAuth 进行登录，你可以在 /mcp 菜单中触发此过程。

选择作用域：local、project 还是 user

Scope 决定了谁能看到服务器以及在哪里存储配置。Claude Code 支持三种作用域，选择正确的作用域可以在不将秘密暴露到你的仓库的情况下，与团队共享安全的服务器。

使用 --scope 标志设置作用域，例如 claude mcp add --scope project ...。Project scope 会写入一个已提交的 .mcp.json 文件，所以切勿将原始 token 放入其中；而是引用一个环境变量。Local scope 是默认且最安全的测试新服务器的位置。如果你还构建了 Claude Code skills，请保持服务器作用域和技能作用域的一致性，这样队友拉取仓库时就能获得可用的设置。

如何使用 claude mcp add 添加服务器？

所有服务器的模式都是相同的：一个名称、一个可选的传输标志和一个命令或 URL。-- 分隔符标记了本地命令及其参数的开始。

添加一个作用域限制在一个文件夹内的本地文件系统服务器，以便 agent 只能触及你允许的内容：

claude mcp add filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem ~/projects/my-app

将秘密作为环境变量传递而不是硬编码它们：

claude mcp add my-api --env API_KEY=your_key_here -- node ./my-mcp-server.js

添加一个带有传输方式和 URL 的远程服务器：

claude mcp add --transport sse linear https://mcp.linear.app/sse

然后管理你已有的内容：

• claude mcp list 显示所有注册的服务器及其状态。
• claude mcp get <name> 打印单个服务器的配置。
• claude mcp remove <name> 取消注册它。
• /mcp（在会话中输入）显示实时连接状态并运行 OAuth。

请将标志的使用保持接近官方文档；供应商偶尔会更改服务器的包名或 URL，因此最好复制服务器自身的 README 中的当前值，而不是猜测。

值得连接的常见 MCP 服务器

从一个能消除实际麻烦的服务器开始，证明它有效后再添加更多。这些是开发者首先选择的，也是它们各自解锁的功能。

Playwright MCP server 是前端工作的佼佼者：agent 会打开你的页面，点击流程，并报告遇到什么错误以及截图。数据库服务器对于只读的 schema 问题很有用，但要将其作用域限制为只读副本，以防意外查询写入数据。当你开始将多个服务器连接起来时，请使用 Claude Code subagents 将繁重的工作路由到专用工作进程，以保持主会话的响应性。

场景：连接 GitHub MCP 服务器以打开 PR

假设你想让 agent 在一个仓库中处理 issues 并打开 pull requests。GitHub 托管了一个官方的远程 MCP 服务器，所以你无需在本地安装任何东西。

1. 注册托管服务器：

   claude mcp add --transport http github https://api.githubcopilot.com/mcp/
   

2. 在 Claude Code 中输入 /mcp，选择 github，并在浏览器中完成 OAuth 登录。令牌保留在 GitHub 端；你永远不会将其粘贴到文件中。

3. 使用 claude mcp list 确认工具已加载。

4. 现在用自然语言提问：

   • "列出标记为 bug 的 open issues 并总结前三个。"
   • "从 fix/login-redirect 打开一个发给 main 分支的草稿 PR，并附上简短描述。"
   • "阅读 PR #214，并标记任何涉及身份验证的内容。"

agent 会读取 issue 线程、起草 PR 内容，并链接正确的 issues，所有这些都无需你离开终端。首先授予 GitHub app 对单个仓库的访问权限，审查 agent 提出的内容，只有在你信任流程后才扩大权限。服务器完整的工具列表和自托管选项记录在 GitHub MCP server repo 中。

连接 MCP 服务器安全吗？

MCP 服务器可以在你的机器上运行代码或操作你的账户，所以要像安装依赖一样对待每一个服务器：只连接你信任的服务器。风险是真实的，因为恶意或有缺陷的服务器可能会泄露文件或使用你的凭证执行破坏性操作。

在添加服务器之前，请通过以下清单进行检查：

• 确认来源。优先选择官方供应商服务器（GitHub、Sentry）或已发布的参考服务器，而不是未知包。
• 阅读它暴露了哪些工具。一个“读取我的 issues”的服务器不应该请求写入整个磁盘的权限。
• 作用域要严格。将文件系统服务器指向单个项目文件夹，将数据库服务器指向只读副本。
• 将秘密排除在 .mcp.json 之外。使用环境变量，绝不要提交真实的 token。
• OAuth 授予最小权限。除非你信任它，否则不要让 GitHub app 访问整个组织，而只给一个仓库的访问权。
• 在批准之前审查操作。阅读 agent 提出的 PR 或查询；不要自动批准来自新服务器的写入操作。

Anthropic 对获取不可信网页内容的服务器提出了提示注入风险警告，所以要对任何拉取任意页面的服务器格外小心。当前的安全性指南可以在 Claude Code MCP 文档 查阅。

故障排除 MCP 连接问题

大多数失败是配置或认证问题，而不是协议本身的问题。请按以下顺序进行排查：

• 未列出服务器： 重新运行 claude mcp list。如果它丢失了，说明 add 命令可能失败了；检查 -- 分隔符或包名是否有拼写错误。

• /mcp 显示失败状态： 进程无法启动。对于 stdio 服务器，请在终端中运行原始命令（例如 npx 行）以查看实际错误。

• 认证失败： 打开 /mcp，选择服务器，并重新执行 OAuth 流程。对于基于 token 的服务器，确认环境变量是否已设置在启动 Claude Code 的 shell 中。

• 工具未出现： 重启 Claude Code 会话以便它重新加载服务器能力，然后验证作用域是否是当前项目可见的范围。

• 作用域错误： 使用 --scope local 添加的服务器对队友不可见；如果应该共享，请使用 --scope project 重新添加。

当远程服务器更改其 URL 或包名重命名时，你保存的配置就会过时。请从服务器的 README 中获取当前值并重新添加，而不是盲目编辑。

关键要点总结

MCP 将 Claude Code 从一个文件和 shell agent 升级为一个可以与你的真实工具对话的 agent。使用 claude mcp add 添加服务器，选择 stdio 用于本地数据，选择 HTTP/SSE 用于托管服务，并通过作用域确定谁应该看到该服务器。首先连接一个有用的服务器，GitHub 服务器是一个很好的起点，并且在信任它之前，请验证每个服务器的来源和权限。将 token 保存在环境变量中，严格限制文件系统和数据库访问范围，并在新服务器获得信任之前，审查 agent 的所有操作。