Obsidian MCP

obsidian-mcp

可将任意 Obsidian 仓库转化为可供 AI 查询的知识图谱的 MCP 服务。

与现有 24+ 个 Obsidian MCP 服务相比，它的不同之处：

• 图谱优先 — 通过 [[wikilinks]] 实现 BFS、最短路径、连通分量和桥接点检测
• 无需基础设施 — 无需数据库、无需运行 Obsidian，也无需 API 密钥
• 不受仓库结构限制 — 适用于任何现有仓库，无需特定结构
• 写入时考虑反向链接 — move_note 会自动更新仓库中的所有引用
• 体积小 — 4 个运行时依赖，打包后约 42KB

快速开始

npx obsidian-mcp --vault ~/my-obsidian-vault

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp", "--vault", "/path/to/vault"]
    }
  }
}

Claude Code

claude mcp add obsidian -- npx -y obsidian-mcp --vault /path/to/vault

工具（12 个）

阅读与发现

工具	描述
vault_stats	概览：笔记总数、标签、链接、孤立笔记、连通分量、热门标签/枢纽
read_note	完整内容 + frontmatter + 链接 + 反向链接 + 章节
search_notes	按标签、文件夹、frontmatter、关键词筛选。可组合使用

图谱遍历

工具	描述
graph_neighbors	笔记的直接链接和反向链接
graph_traverse	从某个笔记开始进行 BFS/DFS，深入 N 跳，并支持按标签筛选
graph_shortest_path	两个笔记之间最短的链接链路
graph_analyze	连通分量、孤立笔记、桥接点、枢纽、失效链接

写入与操作

工具	描述
create_note	创建笔记，添加内容和 frontmatter
patch_note	追加、前置或替换章节。更新 frontmatter
move_note	重命名/移动笔记，并自动更新仓库中的所有反向链接
delete_note	删除笔记并报告失效链接
manage_tags	添加/移除/重命名标签（支持在整个仓库范围内重命名）

配置

默认无需配置。可在仓库根目录中添加 .obsidian-mcp.json：

{
  "ignore": ["templates/", "daily-notes/", ".trash/"],
  "watchDebounce": 100,
  "maxTraversalDepth": 10,
  "maxSearchResults": 500
}

CLI 参数

--vault <path>       Path to Obsidian vault (required)
--verbose            Enable debug logging
--log-level <level>  error | warn | info | debug (default: info)

工作原理

1. 启动时扫描所有 .md 文件并构建内存图谱（1,000 篇笔记约需 1–3 秒）
2. 文件监视器检测更改并增量更新图谱（每次更改约需 5 毫秒）
3. Claude 通过 MCP 工具查询图谱，无需重新扫描
4. 写入操作以原子方式同时更新文件系统和图谱

硬编码排除项：.obsidian/、.trash/、node_modules/

开发

npm install
npm test              # Run 66 tests
npm run build         # Build to dist/
npm run dev -- --vault test/fixtures/vault  # Dev mode

许可证

MIT