MCP 上篇从配置到生产力 —— 给 AI 装上手脚前几篇我们解决了AI 怎么想的问题CLAUDE.md Skills。这篇开始解决AI 怎么动的问题——通过 MCP 让 AI 读写文件、操作 GitHub、浏览网页、查询实时文档。你装好 MCP Server 的那一天会感觉 AI 突然活了。MCP 快速回顾30 秒理解三角色架构如果你学过本项目的 008-mcp-learning 模块以下内容帮你快速唤起记忆。如果是第一次接触 MCP这里给你一个最小化理解┌──────────────────┐ │ Claude Code │ ← HostAI 应用发起调用的一方 │ 帮我创建一个 │ │ GitHub Issue │ └────────┬─────────┘ │ MCP 协议JSON-RPC over stdio/SSE │ ┌────────▼─────────┐ │ MCP Server │ ← Server服务进程提供 Tool/Resource/Prompt │ GitHub MCP │ │ - create_issue │ ← ToolAI 可以调用的功能 │ - search_repos │ │ - create_pr │ └────────┬─────────┘ │ HTTPS ▼ ┌──────────────────┐ │ GitHub API │ ← 真正的数据源 └──────────────────┘一句话总结MCP 是一个标准化协议让 AI 应用通过统一接口调用外部工具和数据源。没有 MCP 之前每个 AI 工具都要单独对接每个外部服务——M×N 的集成复杂度。有了 MCP变成 MN。必装 MCP Server 实测以下 5 个 MCP Server 是经过实际项目验证的必备品。每个都给出安装命令、配置示例、典型场景和 Token 消耗。1. GitHub MCP —— 最不可或缺的一个解决什么问题 AI 想查 Issue、创建 PR、读取代码但没有 GitHub 权限。 你只能复制粘贴 Issue 内容给 AI效率极低。 安装不需要手动安装Claude Code 内置了 GitHub MCP 的官方支持。配置示例// ~/.claude/mcp.json 或项目 .mcp.json{mcpServers:{github:{type:stdio,command:npx,args:[-y,anthropic/mcp-server-github],env:{GITHUB_TOKEN:${GITHUB_TOKEN}}}}}典型使用场景场景一自动查询相关 Issue 你: 修一下登录页的 bug AI: 调用 search_issues(login bug) → 找到 3 个相关 Issue → 读完 Issue 上下文 → 理解了问题的完整背景 → 开始修 没装 GitHub MCP 的话你要手动找 Issue复制粘贴给 AI。 场景二让 AI 直接创建 PR 你: 功能做完了帮我提个 PR AI: 调用 create_pr(title, body, branch) → PR 创建完成 → 返回 PR 链接 没装 GitHub MCP 的话你要打开网页手动填 PR 描述。 场景三Review 时自动检查关联 Issue AI: 我看了这段代码但我先查一下关联的 Issue #42 → 调用 get_issue(42) → Issue 里说需要支持 OAuth 登录但这段代码只管本地登录 → 发现了功能遗漏Token 消耗GitHub MCP 暴露了 ~30 个 Tool。全部加载大约占用 3000 Token。启用 Tool Search 后下文会讲实际开销降至 ~500 Token。2. Filesystem MCP —— AI 的眼睛和手解决什么问题 Claude Code 默认只能操作当前项目目录。 当需要跨项目操作读其他项目的配置、写共享脚本时 必须手动切换目录或复制路径。 配置示例{mcpServers:{filesystem:{type:stdio,command:npx,args:[-y,anthropic/mcp-server-filesystem],env:{ALLOWED_DIRECTORIES:/Users/me/projects,/Users/me/dotfiles}}}}典型使用场景场景一跨项目参考 你: 参考项目 B 的数据库配置帮我写项目 A 的 AI: 用 Filesystem MCP 读 ~/projects/B/config/database.yml → 读 ~/projects/A/config/database.yml → 生成适应 A 的配置 没装的话AI 只能看到项目 A 的文件看不到 B。 场景二管理 dotfiles 你: 帮我更新 zsh 配置加一个新 alias AI: 读 ~/.zshrc → 修改 → 写回 → 这在 Claude Code 默认项目范围外必须有 Filesystem MCP安全提醒ALLOWED_DIRECTORIES一定要精确设置。不要写成/或/Users/me这种范围。越精确越安全。3. Context7 MCP —— 实时文档注入解决什么问题 AI 的知识有截止日期。当你用新版框架/库时 AI 可能给出过时的 API 用法。Context7 让 AI 能实时查询最新文档。 配置示例{mcpServers:{context7:{type:stdio,command:npx,args:[-y,anthropic/mcp-server-context7]}}}使用前后对比没装 Context7 你: 用 Pydantic v3 的 strict mode 做数据校验 AI: 用 v2 的 API 写法因为它的训练数据里 v3 还不完整 → 代码报错你 debug 了 20 分钟才发现版本问题 装了 Context7 你: 用 Pydantic v3 的 strict mode 做数据校验 AI: 调用 context7_search(Pydantic v3 strict mode) → 查到最新文档 → 用 v3 的 API 写代码 → 一次跑通什么时候 Context7 价值最大用 Beta/新发布的框架版本用更新频繁的库Next.js、React 等AI 总是给出不存在的 API 名称时4. Playwright MCP —— 浏览器自动化解决什么问题 AI 写完前端代码后你总要手动打开浏览器验证。 Playwright MCP 让 AI 自己能打开网页、截图、检查元素。 配置示例{mcpServers:{playwright:{type:stdio,command:npx,args:[-y,anthropic/mcp-server-playwright]}}}典型使用场景场景一AI 自己验证前端改动 你: 把首页的按钮颜色改成蓝色 AI: 改代码 → playwright_navigate(http://localhost:3000) → playwright_screenshot() → 改好了这是新按钮的截图你看颜色对吗 你看了一眼截图 → 再深一点 → 不用自己切浏览器刷新 场景二E2E 测试的辅助 AI: 让我跑一下注册流程的 E2E 测试 → 打开页面 → 填表单 → 点提交 → 截图验证 → 注册流程跑通了三张截图都符合预期 场景三爬取需要 JS 渲染的页面 AI: 这个网站的文档是 JS 渲染的直接 fetch 拿不到内容 → 用 Playwright 打开页面 → 等待渲染 → 获取完整 DOM5. Brave Search MCP —— 联网搜索解决什么问题 AI 的知识被锁定在训练日期。面对 2026 年的新技术、 实时事件、最新 Best Practice需要联网搜索。 配置示例{mcpServers:{brave-search:{type:stdio,command:npx,args:[-y,anthropic/mcp-server-brave-search],env:{BRAVE_API_KEY:${BRAVE_API_KEY}}}}}典型场景- Next.js 最近有什么重大更新→ Brave Search → 查到最新的 RFC - 这个 Bug Stack Overflow 上有没有人遇到过→ 搜索 → 找到解决方案 - 有没有比这个库更好的替代品→ 搜索对比 → 给出推荐五个 MCP Server 总结MCP Server核心能力Token 开销必装指数前置条件GitHubIssue/PR/代码操作~500⭐⭐⭐⭐⭐GitHub TokenFilesystem跨项目文件读写~200⭐⭐⭐⭐⭐无Context7实时文档查询~300⭐⭐⭐⭐无Playwright浏览器自动化~400⭐⭐⭐⭐无Brave Search联网搜索~200⭐⭐⭐Brave API Key项目级 vs 用户级 vs 全局配置MCP 配置可以放在三个层级每个层级有不同的适用场景~/.claude/mcp.json ← 用户级全局生效 │ ├── 最常用。所有项目共享的 MCP Server 放这里。 │ 例GitHub、Filesystem、Brave Search │ 项目根目录/.mcp.json ← 项目级优先于用户级 │ ├── 项目专用的 MCP Server 放这里。 │ 例公司内部 API 的 MCP Server、项目特定的数据源 │ Plugin 自带的 .mcp.json ← 插件级通过 Plugin 安装 │ └── 详见第 9-10 篇 Plugins优先级规则项目级 .mcp.json 用户级 ~/.claude/mcp.json 同名 Server 如果项目级和用户级都配置了同名 Server项目级的配置会合并 不是覆盖——项目级的 env 会追加到用户级配置中 最佳实践 通用 Server → 用户级 项目专用 Server → 项目级随 Git 版本管理 不要在项目级重复定义用户级已有的 Server实际配置示例// ~/.claude/mcp.json用户级——通用{mcpServers:{github:{/* ... */},filesystem:{/* ... */},context7:{/* ... */}}}// 项目/.mcp.json项目级——项目专用{mcpServers:{company-api:{type:stdio,command:python,args:[-m,company_mcp.server],env:{COMPANY_API_KEY:${COMPANY_API_KEY}}}}}安全配置清单MCP Server 本质上是一个可以执行任意命令的进程。安全配置不是可选。五项安全规则1. 最小权限原则 ❌ ALLOWED_DIRECTORIES: / ✅ ALLOWED_DIRECTORIES: /Users/me/projects/my-app 2. 环境变量隔离 ❌ 直接在 .mcp.json 里写 API Key env: { GITHUB_TOKEN: ghp_xxxxxxxxxxxx } ✅ 用变量引用Key 存在系统的环境变量或 .env 里.env 不入 Git env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } 3. 路径白名单 Filesystem MCP 的目录白名单必须精确到具体项目。 如果你有 3 个项目写 3 条路径不要写父目录。 4. 敏感 Tool 确认 对于高权限操作delete_repo、force_push 等 保持 Claude Code 的权限确认为 ask 而非 allow。 在 CLAUDE.md 或 settings.json 中设置 危险命令rm -rf、git push --force、数据库 DROP→ 必须确认 5. 来源可信 只安装来自以下来源的 MCP Server - 官方维护anthropic/* - GitHub 验证过的组织 - 你自己写/审查过的 警惕不要随便装来源不明的 MCP Server。 它能读你的文件、访问你的网络、执行系统命令。安全速查表□ 所有 API Key 都用 ${VAR} 引用不硬编码 □ Filesystem MCP 的 ALLOWED_DIRECTORIES 精确到项目 □ 危险 Tooldelete/drop/force-push的权限设为 ask □ 不在公共仓库的 .mcp.json 中包含敏感信息 □ 定期审查已安装的 MCP Server 是否还在用Tool Search把 Token 开销降低 85%问题Tool 描述吃掉了你的上下文每个 MCP Server 会注册若干 Tool每个 Tool 有一个描述。AI 启动时会加载所有 Tool 的描述GitHub MCP: ~30 个 Tool × 100 Token/个 3000 Token Playwright: ~20 个 Tool × 100 Token/个 2000 Token Filesystem: ~10 个 Tool × 100 Token/个 1000 Token Context7: ~5 个 Tool × 100 Token/个 500 Token Brave Search: ~3 个 Tool × 100 Token/个 300 Token 其他 Server... ~50 个 Tool × 100 Token/个 5000 Token ───────────────────────────────────────────────────── 总计: 118 个 Tool ≈ 11800 Token11800 Token 只用来告诉 AI “有哪些工具可用”。如果你装了 10 MCP ServerTool 描述可能占用 20000 Token。解决方案Tool SearchTool Search 是 Claude Code 的内置机制——AI 不主动加载所有 Tool而是在需要时搜索传统模式 Tool Search 模式 启动时加载所有 118 个 Tool 的描述 启动时只加载 Tool 索引~300 Token ↓ ↓ AI 从 118 个 Tool 中选择合适的 AI 判断需要什么能力 ↓ ↓ 执行选中的 Tool AI 搜索匹配的 Tool关键词匹配 ↓ ↓ 只加载匹配的 Tool 描述~500 Token ├── 不匹配的 Tool 不加载 └── 节省上下文 Token 对比 全部加载~11800 Token 搜索 加载 3-5 个~800 Token → 节省 85%如何确保 Tool Search 生效Tool Search 默认开启但你需要确保 Tool 的描述写得好# ❌ 描述太模糊Tool Search 匹配不到tool(description查询数据)defquery_data(query:str):...# ✅ 描述具体包含关键词tool(description查询 PostgreSQL 数据库。支持 SELECT 语句返回 JSON 格式结果。)defquery_database(sql:str):...Tool 的description是 Tool Search 的唯一匹配依据。描述越具体搜索命中越准确。常见问题排查Q装了 MCP Server 但 AI 不调用A三步排查法claude mcp list—— 确认 Server 是否在列表中且状态正常claude mcp logs server-name—— 查看 Server 是否有启动错误检查 Tool 描述是否太模糊 —— AI 基于描述判断是否调用描述不行就不会调用QMCP Server 经常超时怎么办AMCP Server 默认超时 60 秒。如果 Server 需要更长时间{mcpServers:{slow-server:{type:stdio,command:...,timeout:120// 扩大到 120 秒}}}Q能不能动态切换 MCP ServerA修改.mcp.json后Claude Code 会在下次会话自动加载新配置。当前会话中不会动态生效。最快的方式是/exit然后重新进入。延伸阅读Claude Code MCP 官方文档MCP 协议规范