Claude Code CLI MCP 指南：连接外部数据与服务
学习目标
完成本教程后，你将能够：
- 理解 MCP（模型上下文协议）如何与 Claude Code 配合工作
- 使用
claude mcp add命令为 Claude Code CLI 添加 MCP 服务器 - 检查 MCP 服务器的连接状态
- 在 Claude Code 对话中使用 MCP 工具
- 管理服务器作用域（本地、用户、项目）
预计用时： 15–20 分钟
难度： 初级
本篇覆盖哪个版本？ 本教程覆盖 Claude Code CLI——Claude Code 的命令行版本。MCP 服务器通过 claude mcp 命令和 .mcp.json 或 ~/.claude.json 配置文件管理。如果你需要桌面客户端，请阅读 Claude 桌面客户端 MCP 指南。
前置条件
开始之前，请确保已准备以下内容：
| 要求 | 说明 |
|---|---|
| 已安装 Claude Code CLI | claude --version 应显示版本号。未安装？请先阅读 Claude Code CLI 入门指南 |
| 已登录 Claude Code | 运行 claude 并用你的 Anthropic/Claude 账户登录 |
| 打开终端 | 本教程的所有命令都在终端中运行 |
什么是 MCP？
MCP（Model Context Protocol，模型上下文协议）是一种开放标准，让 Claude Code 等 AI 助手能够连接到外部工具和数据源。每个工具不需要自己构建定制集成，大家都用同一个协议沟通。
MCP 服务器是一个小程序，向 AI 助手暴露工具、数据或服务。例如：
- GitHub MCP 服务器让 Claude Code 读取 Issue、创建 Pull Request、浏览仓库
- 数据库 MCP 服务器让 Claude Code 用自然语言查询数据库
- 问题追踪 MCP 服务器让 Claude Code 直接访问 JIRA、Linear 或 Notion
Claude Code 支持两种类型的 MCP 服务器：
- HTTP 服务器（推荐）：托管在 URL 上，无需本地进程
- Stdio 服务器：作为本地程序在机器上运行
Claude Code MCP 的工作原理
Claude Code CLI 内置了 MCP 支持。你可以用 claude mcp add 命令添加服务器，该命令会将服务器配置写入文件。有三种作用域：
- 本地（默认）：仅对你可见，只在当前项目目录生效
- 用户：仅对你可见，在你的所有项目中生效
- 项目：通过提交到仓库的
.mcp.json与团队成员共享
一旦添加服务器，其工具在每次会话中都可被 Claude Code 使用。Claude 会根据你的提示自动选择正确的工具。
第 1 步：检查 MCP 设置
首先确认你的 Claude Code 版本支持 MCP：
claude --version你应该看到： 版本号（v2.1.x 或更高）。所有最近的 Claude Code 版本都内置了 MCP 支持。
现在检查已有哪些服务器：
claude mcp list你应该看到： 已配置的 MCP 服务器列表，或提示"未配置 MCP 服务器"。
第 2 步：寻找 MCP 服务器
Claude Code MCP 服务器可在多个来源找到：
- 站内 MCP 目录：浏览 /mcp——55+ 款精选 MCP 服务器，可直接连接
- Anthropic 目录：claude.ai/directory——Anthropic 审核过的连接器
- GitHub：搜索
mcp-server——有数千个社区服务器 - npm：许多服务器可通过
npx安装
本教程将连接 **GitHub MCP 服务器**——最受欢迎的服务器之一，让 Claude Code 可以读取仓库、Issue 和 Pull Request。
第 3 步：添加 HTTP MCP 服务器
HTTP 服务器是连接远程 MCP 服务器的推荐方式。它们托管在 URL 上，无需本地设置。
打开终端并注册 GitHub MCP 服务器：
claude mcp add --transport http github https://api.githubcopilot.com/mcp/你应该看到： 确认消息，如 Added HTTP MCP server github with URL: ...，后面跟着显示配置文件路径的 File modified: 行。
添加 Stdio 服务器（替代方案）
如果服务器作为本地命令运行，使用 stdio 传输：
claude mcp add my-db-server -- npx -y @modelcontextprotocol/server-postgres你应该看到： 命令无错误完成，Claude Code 将服务器条目写入配置文件。
第 4 步：检查连接状态
验证服务器已连接：
claude mcp list你应该看到： 服务器显示状态指示器：
| 状态 | 含义 |
|---|---|
✔ Connected | 可正常使用 |
! Needs authentication | 服务器需要浏览器登录或令牌 |
✘ Failed to connect | 服务器未响应 |
你也可以检查特定服务器：
claude mcp get github你应该看到： 服务器详情，包括传输类型、URL 和状态。
第 5 步：在对话中使用 MCP 工具
现在启动 Claude Code 会话并使用 MCP 工具：
claude然后输入使用已连接服务的提示，例如：
列出 facebook/react 仓库中的开放 Issue你应该看到： Claude Code 自动调用 GitHub MCP 服务器的工具。Claude 第一次使用工具时会请求你的许可，批准后继续。工具调用在 Claude 的输出中带有服务器名称标注，你可以确认答案来自 MCP 服务器。
你也可以在会话中输入 /mcp 查看可用的 MCP 工具。
第 6 步：更改服务器作用域（可选）
默认情况下，服务器以本地作用域添加（仅对你可见，在当前项目中）。要为所有项目注册服务器：
claude mcp add --scope user github -- npx -y @modelcontextprotocol/server-github要通过 .mcp.json 与团队成员共享服务器：
claude mcp add --scope project github -- npx -y @modelcontextprotocol/server-github第 7 步：移除服务器（可选）
如果不再需要某个服务器，移除它：
claude mcp remove github你应该看到： 服务器从 claude mcp list 中消失。
排查问题
| 问题 | 原因 | 解决方法 | |
|---|---|---|---|
claude: command not found | 未安装 Claude Code CLI | 安装：`curl -fsSL https://claude.ai/install.sh | bash`，然后重启终端 |
claude mcp 不可识别 | Claude Code 版本过旧 | 更新：claude update | |
! Needs authentication | 服务器需要 OAuth 或令牌 | 查看服务器 README 了解认证要求。使用 --header 传递令牌，或运行 claude 触发浏览器登录 | |
✘ Failed to connect | 服务器 URL 错误或不可达 | 验证 URL 和网络连接。尝试 curl <url> 测试 | |
npx: command not found | 未安装 Node.js | 从 nodejs.org 安装 Node.js LTS，然后重启终端 | |
| 服务器已连接但工具失败 | 服务器需要 API key 或环境变量 | 查看服务器文档了解所需的环境变量，设置后重启 Claude Code |
常见问题
使用 MCP 需要付费计划吗？ 需要。MCP 支持要求付费的 Claude 计划（Pro、Max 或更高）。
CLI 和桌面端可以使用相同的 MCP 服务器吗？ 可以——你可以用 claude mcp add-from-claude-desktop 将桌面端服务器导入 CLI。它们共享相同的配置格式。
本地、用户和项目作用域有什么区别？ 本地作用域将服务器保存到项目的 .mcp.json；用户作用域保存到 ~/.claude.json；项目作用域保存到 .mcp.json（与团队成员共享）。
如何在会话中查看可用的 MCP 服务器？ 在 Claude Code 会话中输入 /mcp。
可以将 Claude Code 作为 MCP 服务器暴露给其他工具吗？ 可以——运行 claude mcp serve 将 Claude Code 的工具暴露给其他 MCP 客户端。这是高级用法。
下一步
- 浏览站内 MCP 目录——55+ 款精选 MCP 服务器等你连接
- 在 Claude Code CLI 入门指南 中学习更多 Claude Code CLI 命令
- 如果你偏好图形界面，请阅读 Claude 桌面客户端 MCP 指南
