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

本机参考：全局 MCP server 2 个（obsidian / unity-mcp），项目级 MCP server 2 个（obsidian-hybrid-search / chrome-devtools），另有 codegraph MCP 常驻。配置结构照实，API key 与内网地址已脱敏。

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 架构

scss 复制代码

┌────────────┐   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`	等价于改配置文件

经验：全局只放"所有项目都要用"的（如 obsidian、unity-mcp）；项目专用放项目级（如 chrome-devtools、obsidian-hybrid-search 只在 vault 目录用）。配两处是冗余的，一处即可。

3. 本机 MCP 配置案例

3.1 obsidian ------ 读写知识库

json 复制代码

"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 ------ 语义检索

json 复制代码

"obsidian-hybrid-search": {
  "command": "npx",
  "args": ["-y", "-p", "obsidian-hybrid-search@0.13.24", "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 ------ 联网搜索

json 复制代码

"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 编辑器

json 复制代码

"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 配置模板

json 复制代码

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

4.3 验证

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

4.4 写一个自定义 MCP server

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

perl 复制代码

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

python 复制代码

# server.py ------ 极简示例
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-mcp")

@mcp.tool()
def hello(name: str) -> str:
    """向调用者打招呼。"""
    return f"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. 与其它扩展点的关系

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