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

1. MCP 是什么

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

类比：

1. CC 是大脑，MCP 是给大脑接的感官和手脚
2. 一个 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":"****"// 脱敏}}}

1. 依赖：Obsidian 桌面端 + obsidian-local-rest-api 插件（在本机 127.0.0.1 起 HTTPS 服务）
2. 提供工具：read_file / search / patch_file / list_files 等
3. 坑：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"}}

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

3.3 chrome-devtools —— 联网搜索

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

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

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

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

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

3.5 codegraph —— 代码图谱

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

4. 如何配置一个新 MCP

4.1 找现成 server

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

4.2 配置模板

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

4.3 验证

1. 重启 CC 会话
2. /mcp 查看 server 连接状态（绿色=OK，红色=失败）
3. 直接调 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 名要见名知意，工具多了才好找

6. 与其它扩展点的关系

1. MCP 是"手"，skill 是"脑"——skill 正文里调用 MCP 工具，组合成工作流（kb-lookup 调 obsidian MCP 就是范例）
2. Hooks 可拦截 MCP 调用做安全审计
3. 配置在 settings.json，与权限/插件同一文件