Claude Code 扩展点：MCP —— 给 AI 接入外部工具的完整手脚

作者：袖梨 2026-08-15

处理Claude Code 扩展点：MCP —— 给 AI 接入外部工具的完整手脚这类问题时，先确认目标场景，再按步骤核对配置或玩法细节。

1. MCP 是什么

MCP（Model Context Protocol）= 外部工具的标准接入协议。它让 CC 能调用任意外部能力——读数据库、查文档、控制浏览器、操作 Unity 编辑器……而不需要 Anthropic 内置。

类比：

CC 是大脑，MCP 是给大脑接的感官和手脚
一个 MCP server = 一组工具的集合，暴露给 CC 调用

CC 通过 MCP 调用工具时，工具名形如 mcp__<server名>__<工具名>，比如 mcp__obsidian__search_notes。

2. 工作原理

2.1 架构

┌────────────┐   MCP 协议   ┌──────────────┐   HTTP/WS    ┌──────────┐│ Claude Code│◄───────────►│ MCP server    │◄────────────►│ 外部能力  ││  (客户端)   │  stdio/SSE  │  (工具集合)    │              │  (服务)   │└────────────┘             └──────────────┘               └──────────┘

两种传输方式：

方式	说明	典型场景
stdio	server 是本地进程，通过标准输入输出通信	本地 CLI 工具（uvx/npx 起的 server）
SSE / HTTP	server 是远程 HTTP 服务	远程服务、局域网服务

本机用的都是 stdio 本地进程。

2.2 配置位置

位置	文件	生效范围
全局	`~/.claude/settings.json` 的 `mcpServers`	所有项目
项目级	`<项目>/.claude/settings.json` 的 `mcpServers`	该项目
CLI 管理	`claude mcp add / list / remove`	等价于改配置文件

3. 本机 MCP 配置案例

3.1 obsidian —— 读写知识库

"mcpServers":{"obsidian":{"command":"uvx","args":["mcp-obsidian"],"env":{"OBSIDIAN_API_KEY":"****"// 脱敏}}}

依赖：Obsidian 桌面端 + obsidian-local-rest-api 插件（在本机 127.0.0.1 起 HTTPS 服务）
提供工具：read_file / search / patch_file / list_files 等
坑：Obsidian 没开就报连接拒绝；uvx 来自 uv（brew install uv）

3.2 obsidian-hybrid-search —— 语义检索

"obsidian-hybrid-search":{"command":"npx","args":["-y","-p","[email protected]","obsidian-hybrid-search-mcp"],"env":{"OBSIDIAN_VAULT_PATH":"/Users/xxx/.../knowledge_base","OBSIDIAN_PREFIX":"kb_","OBSIDIAN_IGNORE_PATTERNS":".obsidian/**,90-Templates/**,*.canvas,*.base","OPENAI_BASE_URL":"http://127.0.0.1:11434/v1","OPENAI_EMBEDDING_MODEL":"bge-m3"}}

能力：BM25 关键词 + 向量语义双路混合检索（RRF 融合），比纯关键词搜召回更准
关键配置：embedding 走本地 ollama（127.0.0.1:11434，模型 bge-m3）——因为 HuggingFace 被墙，自动下模型的方案必失败
坑：中文查询不能走 fulltext，混合检索默认适合中文

3.3 chrome-devtools —— 联网搜索

"chrome-devtools":{"command":"npx","args":["-y","chrome-devtools-mcp@latest","--wsEndpoint","ws://127.0.0.1:9222/devtools/browser/****"]}

能力：控制本机 Chrome（导航/抓取页面/执行 JS），是 CC 的联网眼睛
为什么需要：本机 CC 走自定义后端，WebSearch 内置工具实际不可用 → 靠它控制真实浏览器搜索最新资料
前置：Chrome 需以 --remote-debugging-port=9222 启动

3.4 unity-mcp —— 操控 Unity 编辑器

"unity-mcp":{"command":"/Users/xxx/.../relay_mac_arm64","args":["--mcp","--instance-id","****"]}

能力：双层桥接让 AI 操控 Unity 编辑器——创建对象 / 写脚本 / 读 Console / 跑测试
配合：unity-mcp-skill
案例：Unity 游戏自动化开发预研、AI 生成 Spine 动画预研

3.5 codegraph —— 代码图谱

能力：SQLite 代码知识图谱，符号/调用关系/文件树亚毫秒查询，CC 改代码前先查图谱给"外科手术式上下文"
定位：确定性索引，零 token 成本、100% 本地，减少 grep/Read 调用

4. 如何配置一个新 MCP

4.1 找现成 server

官方 marketplace（/mcp 菜单浏览）
GitHub 搜 xxx-mcp（如 mcp-obsidian、chrome-devtools-mcp）
大部分本地 server 用 npx -y <包名> 或 uvx <包名> 直接起

4.2 配置模板

"mcpServers":{"我的工具":{"command":"npx","args":["-y","<包名>","<参数>"],"env":{"KEY":"value"}}}

4.3 验证

重启 CC 会话
/mcp 查看 server 连接状态（绿色=OK，红色=失败）
直接调 mcp__<名字>__* 工具确认返回正常

4.4 写一个自定义 MCP server

如果现成的没有，可以自己写。最小结构（Python，用官方 SDK）：

my-mcp/├── server.py      # 实现工具└── requirements.txt

# server.py —— 极简示例from mcp.server.fastmcp import FastMCPmcp = FastMCP("my-mcp")@mcp.tool()defhello(name: str) ->str:    """向调用者打招呼。"""returnf"Hello, {name}!"if __name__ == "__main__":    mcp.run()

配置：command: "python"，args: ["server.py"]。重启会话后即可 mcp__my-mcp__hello。

5. 最佳实践与坑

主题	建议
超时	远程 MCP 调用挂起会中止，`MCP_TOOL_TIMEOUT` 调大（本机 30000）
鉴权	API key 走 `env` 注入，别写死在命令参数里；key 别进 git
密钥脱敏	settings.json 可能被同步备份，key 一律打码处理
server 生命周期	本地 stdio server 随会话起停；Obsidian 依赖桌面进程，Obsidian 关了工具就挂
能用本地不联网	embedding / 索引类优先本地（ollama），避免外网依赖与数据外泄
工具命名	server 名要见名知意，工具多了才好找