07-MCP 上篇：从配置到生产力 —— 给 AI 装上手脚

MCP 上篇：从配置到生产力 —— 给 AI 装上手脚

前几篇我们解决了"AI 怎么想"的问题（CLAUDE.md + Skills）。这篇开始解决"AI 怎么动"的问题——通过 MCP 让 AI 读写文件、操作 GitHub、浏览网页、查询实时文档。你装好 MCP Server 的那一天，会感觉 AI 突然"活了"。

MCP 快速回顾：30 秒理解三角色架构

如果你学过本项目的 008-mcp-learning 模块，以下内容帮你快速唤起记忆。如果是第一次接触 MCP，这里给你一个最小化理解：

┌──────────────────┐ │ Claude Code │ ← Host（AI 应用，发起调用的一方） │ "帮我创建一个 │ │ GitHub Issue" │ └────────┬─────────┘ │ MCP 协议（JSON-RPC over stdio/SSE） │ ┌────────▼─────────┐ │ MCP Server │ ← Server（服务进程，提供 Tool/Resource/Prompt） │ GitHub MCP │ │ - create_issue │ ← Tool：AI 可以调用的功能 │ - search_repos │ │ - create_pr │ └────────┬─────────┘ │ HTTPS ▼ ┌──────────────────┐ │ GitHub API │ ← 真正的数据源 └──────────────────┘

一句话总结：MCP 是一个标准化协议，让 AI 应用通过统一接口调用外部工具和数据源。没有 MCP 之前，每个 AI 工具都要单独对接每个外部服务——M×N 的集成复杂度。有了 MCP，变成 M+N。

必装 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 打开页面 → 等待渲染 → 获取完整 DOM

5. 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 总结

项目级 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 精确到项目 □ 危险 Tool（delete/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 Token

11800 Token 只用来告诉 AI “有哪些工具可用”。如果你装了 10+ MCP Server，Tool 描述可能占用 20000+ Token。

解决方案：Tool Search

Tool 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：三步排查法：

1. claude mcp list—— 确认 Server 是否在列表中且状态正常
2. claude mcp logs <server-name>—— 查看 Server 是否有启动错误
3. 检查 Tool 描述是否太模糊 —— AI 基于描述判断是否调用，描述不行就不会调用

Q：MCP Server 经常超时怎么办？

A：MCP Server 默认超时 60 秒。如果 Server 需要更长时间：

{"mcpServers":{"slow-server":{"type":"stdio","command":"...","timeout":120// 扩大到 120 秒}}}

Q：能不能动态切换 MCP Server？

A：修改.mcp.json后，Claude Code 会在下次会话自动加载新配置。当前会话中不会动态生效。最快的方式是/exit然后重新进入。

延伸阅读

• Claude Code MCP 官方文档
• MCP 协议规范