MCP

查 PR 信息

想看看当前仓库的 open PR 有哪些。你打开浏览器 → 登录 GitHub → 找到 PR → 复制内容 → 粘贴给 Claude。来回切了三次。

查数据库

需要确认线上某个用户的订单状态。你连上数据库 → 跑查询 → 导出结果 → 粘贴给 Claude。查一次两分钟，查十次二十分钟。

发通知

Claude 做完代码审查，你想把结果发到团队频道。手动复制 → 打开 Slack → 粘贴发送。每次都是纯手工操作。

适合谁

• 希望让 Claude 接入 GitHub、数据库、内部平台等外部能力的开发者
• 厌倦了在工具之间手动复制粘贴的人
• 理解命令和 Skill 的基本用法，想进一步扩展 Claude 的能力边界

读完后你应该已经能

• 说清 MCP 的定位和三层架构
• 配置和使用一个 MCP server
• 判断"什么时候用 MCP，什么时候用 Memory 就够了"
• 掌握最关键的安全注意事项

前置条件

• Claude Code — 已安装并可用
• MCP Server — 对应服务的 server 包（如 @modelcontextprotocol/server-github）
• 认证信息 — API Token、OAuth 凭据或数据库连接字符串

快速验证清单

# 1. 添加 server
$ claude mcp add my-db -- npx @mcp/server-db

# 2. 确认已注册
$ claude mcp list

# 3. 查看暴露的工具
$ claude mcp get my-db

# 4. 在对话中试用
> "用 my-db 查一下用户表有多少行"

HTTP（推荐远程）

通过 HTTP 连接远程服务。适合第三方服务和企业内网。

# 添加 HTTP MCP server
$ claude mcp add my-server --transport http \
  --url https://api.example.com/mcp

Stdio（本地进程）

通过标准输入输出连接本地进程。适合本地运行的工具。

# 添加本地 MCP server
$ claude mcp add my-local \
  -- npx my-mcp-server

Windows 注意事项

• Shell 差异：Windows 上 Stdio 模式使用的 shell 与 Unix 不同，command 字段要写完整路径或确保命令在 PATH 中
• 环境变量：使用 ${VAR} 语法，实际变量在 Windows 系统环境变量中设置
• 路径写法：配置文件中路径使用正斜杠 /，或使用转义的反斜杠 \\

OAuth 2.0 认证

• 部分 MCP Server 支持 OAuth，Claude 可通过交互式浏览器流程完成授权
• 也可以在配置中预配置凭据（Client ID / Secret），跳过交互步骤
• 适合需要安全接入的企业级服务（如 Google Workspace、Azure DevOps）

组合使用

一个项目可以同时接入多个 MCP Server。比如"每日报告"工作流：GitHub 拉取 PR 统计 → Database 查询销售数据 → Slack 发送报告——全在对话中完成。

Elicitation

有些 MCP Server 在运行时需要用户提供额外信息。Claude 会把 Server 的问题转发给你，你回答后 Claude 再把结果传回去——不需要提前配置所有参数。

动态工具更新

MCP Server 增加或移除工具时，Claude 可以在运行时感知变化，不需要重启会话。比如你中途更新了 Server 版本，新工具立即可用。

工具自动搜索

Claude 会根据当前上下文自动查找可用的 MCP 工具。你不需要记住工具名——只要描述清楚需求，Claude 自动匹配合适的工具。

@ 提及资源

除了工具调用，MCP 还提供资源引用。你可以在 prompt 中用 @ 直接提及某个 MCP 资源（如一份远程文档），Claude 会自动读取其内容。

Subagent 作用域

你可以限制某些 MCP Server 只允许特定 subagent 使用。比如数据库 MCP 只给数据分析 agent 开放，不让代码审查 agent 接触。

插件自带 MCP

插件可以把 MCP Server 打包分发。安装一个插件 = 自动获得它提供的所有 MCP 工具，不需要单独配置 server。

能做什么

• PR 管理：列出、查看、审查、合并 PR
• Issue 管理：创建、搜索、更新、关闭 Issue
• 仓库信息：查看状态、分支、标签
• Commit 操作：查看提交历史、比较差异

实际对话

用户: "列出这个仓库的 open PR"

Claude: 调用 mcp__github__list_prs
→ 返回 PR 列表

用户: "审查 PR #42"

Claude: 调用 mcp__github__pr_review(42)
→ 返回审查结果 + 建议

配置方式

// .mcp.json 中添加数据库 server
{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

实际对话

用户: "查一下最近 7 天的新增用户数"

Claude: 调用 mcp__my-db__query(
  "SELECT COUNT(*) FROM users
   WHERE created_at > NOW() - INTERVAL '7 days'"
)

→ 返回结果: [{ count: 1284 }]

用户: "按天分组呢？"

Claude: 调用 mcp__my-db__query(
  "SELECT DATE(created_at) AS day,
          COUNT(*) AS cnt
   FROM users
   WHERE created_at > NOW() - INTERVAL '7 days'
   GROUP BY day ORDER BY day"
)
→ 返回每日数据，Claude 生成趋势分析

问题场景

• 数据库查询返回几千行结果，撑爆上下文窗口
• GitHub API 返回完整的 diff 内容，token 消耗暴增
• 文件系统读取超大日志文件，对话卡住

控制手段

• 限制 token 数：在工具调用中指定返回上限
• 分页获取：使用 limit 和 offset 参数分批拉取
• 增大上限：需要完整结果时，可增大最大输出到 50,000 tokens

# 增大 MCP 输出上限
$ claude config set mcpMaxOutputTokens 50000

示例：过滤大数据集

# 不要这样（全量拉取）
> "查出所有用户给我看"
→ 返回 10000 行，上下文爆了

# 应该这样（精确查询）
> "查出活跃度前 10 的用户"
→ MCP 只返回 10 条，token 可控

示例：循环处理

# 不要来回对话（每轮都传数据）
> "处理第 1 批" → 返回结果
> "处理第 2 批" → 返回结果（又要传上下文）

# 应该：让 Claude 写代码循环
> "写个脚本遍历所有批次，
    用 MCP 查询并汇总"
→ 一次完成，无 round-trip

工作方式

• 运行 claude mcp serve 后，Claude Code 暴露一组 MCP 工具
• 其他应用（如 Claude Desktop、IDE 插件）可以通过 MCP 协议调用 Claude Code 的能力
• 适合把 Claude Code 嵌入已有工具链中

典型场景

• IDE 集成：让编辑器通过 MCP 直接调用 Claude Code 的文件编辑、代码分析能力
• 工具链串联：把 Claude Code 作为"代码智能"节点接入自动化流水线
• 多 Agent 协作：其他 Agent 通过 MCP 协议调用 Claude Code 完成编码任务

方式 1：CLI 命令

# 添加 MCP server
$ claude mcp add github --transport http --url https://...

# 列出所有 MCP servers
$ claude mcp list

# 查看特定 server 详情
$ claude mcp get github

# 移除 MCP server
$ claude mcp remove github

方式 2：配置文件

// 文件：.mcp.json（项目级）
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

更多管理命令

# 重置项目级审批选择（重新询问权限）
$ claude mcp reset

# 从 Claude Desktop 导入已有配置
$ claude mcp import

已经在 Claude Desktop 里配好了 MCP？用 import 一键导入到 Claude Code，不用重复配置。

企业受管配置

企业可以通过受管设置（Managed Settings）统一向团队分发 MCP 配置。管理员指定允许的 Server 清单和认证方式，团队成员无需单独配置——开箱即用。

• 统一管控：哪些 Server 可以用、权限边界在哪
• 集中认证：由管理员统一维护 Token 和凭据
• 合规审计：所有 MCP 调用可追溯

Schema 不匹配

症状：工具调用报错，提示参数类型不对。

修复：检查参数类型定义。工具期望 JSON 对象但你传了字符串？用 claude mcp get <server> 查看工具的完整 Schema。

权限不足

症状：Server 能连接，但工具调用被拒。

修复：检查 OAuth/Token 配置。确认环境变量中的认证信息有效。试试 claude mcp get <server> 看工具列表。

网络超时

症状：外部服务响应慢，工具调用卡住。

修复：设置超时和重试策略。检查网络连接和代理配置。

返回数据过大

症状：查询结果太多，上下文被撑爆。

修复：在工具调用时使用过滤和分页参数。限制返回的条目数。避免 SELECT * 式的全量查询。

找不到 MCP Server

症状：claude mcp list 里看不到刚添加的 server，或调用时报"server not found"。

修复：确认 server 包已安装（npm list -g 检查）、配置文件路径正确、command 字段的命令可以正常执行。

认证失败

症状：Server 能连接，但每次调用都报 401/403。

修复：检查环境变量是否设置（echo $GITHUB_TOKEN）、确认 Token 权限范围是否足够、重新 export 变量后再启动 Claude Code。

Server 崩溃

症状：调用工具后 Server 无响应或直接退出。

修复：查看 Server 的 stderr 日志、降低并发请求数、简化参数重试。如果 Server 是 Node.js 进程，检查内存是否足够。

到这里，你已经能

• 说清 MCP 的定位和三层架构
• 理解 Server / Tool / Schema 的关系
• 配置和使用 MCP server
• 掌握最关键的安全注意事项
• 判断"何时用 MCP vs Memory"

它和前后章节的关系

• Subagents — agent 可以通过 MCP 访问外部工具
• MCP — 连接外部系统的桥梁
• Hooks — 在 MCP 调用前后自动触发校验
• Plugins — 把 MCP server 打包进插件

继续本课程

• 下一章：Hooks — 在 MCP 调用前后自动触发校验
• CLI — 通过命令行管理 MCP 配置

本章源文件 （点击查看完整内容）

• README.md — MCP 完整配置指南