本机参考：全局 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，与权限/插件同一文件