AI导哈

Obsidian Vault MCP 服务器

一个将Obsidian库的链接图作为可查询工具暴露的MCP服务器，支持查找反向链接、损坏链接、孤立笔记等功能。

  • by JoshuaOliphant
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 JoshuaOliphant/obsidian-vault-mcp

使用说明

黑曜石保险库MCP服务器

MCP（模型上下文协议）服务器，将黑曜石保管库的链接图作为可查询工具公开。直接从Claude Code或任何MCP客户端查找反向链接、断开链接、孤立注释等。

为什么？

Obsidian在GUI中具有出色的图形功能，但AI代理无法通过编程方式查询您的保险库结构。现有的Obsidian MCP服务器要么没有维护，要么缺乏图形感知工具。

此服务器解析vault的markdown文件，构建内存中的链接图，并通过7个专注的工具公开它。

建于 FastMCP 3.所有查询工具返回 结构化的 内容 有输出 模式和携带只读 工具注释 (readOnlyHint, idempotentHint)，这样MCP客户就知道他们可以安全地拨打电话。

工具

工具 说明
get_backlinks 查找链接到给定笔记的所有笔记
get_outgoing_links 查找给定笔记链接到的所有笔记
find_broken_links 查找 [[wiki-links]] 指向不存在的文件
find_orphaned_notes 查找没有入站链接的文件
get_note_info 获取笔记的元数据（标签、字数、链接数）
vault_stats 保险库整体运行状况摘要
refresh_index 编辑磁盘上的笔记后强制重新扫描

设置

先决条件

安装

git clone https://github.com/joshuaoliphant/obsidian-vault-mcp.git
cd obsidian-vault-mcp
uv sync

在Claude代码中配置

添加 ~/.claude/settings.json 在...之下 mcpServers:

{
  "obsidian-vault": {
    "command": "uv",
    "args": [
      "run", "--directory",
      "/path/to/obsidian-vault-mcp",
      "python", "-m", "obsidian_vault_mcp"
    ],
    "env": {
      "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
    }
  }
}

环境变量

变量 必填 默认 描述
OBSIDIAN_VAULT_PATH 是 -- 通往黑曜石金库的绝对路径
OBSIDIAN_SCAN_DIRS 没有 journal,areas,projects,resources,inbox,knowledge 要扫描的逗号分隔的目录名
OBSIDIAN_EXCLUDE_PATTERNS 没有 .claude/,.obsidian/,node_modules/,worktrees/,__pycache__/ 要排除的逗号分隔的路径片段
OBSIDIAN_CACHE_TTL 没有 300 缓存生存时间（秒）

使用示例

一旦注册，这些工具就可以在Claude Code中使用：

> What links to my "Weekly Review" note?
# Claude calls get_backlinks("Weekly Review")

> Are there any broken links in my vault?
# Claude calls find_broken_links()

> Show me notes that nobody links to
# Claude calls find_orphaned_notes()

> How healthy is my vault?
# Claude calls vault_stats()

> I just edited a bunch of notes — re-scan the vault
# Claude calls refresh_index()

演出

在1100文件保险库上测试：

  • 冷扫描：~0.4秒
  • 缓存查询：~20ms
  • 缓存自动刷新基于 OBSIDIAN_CACHE_TTL

发展

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src tests

# Type check
uv run ty check src tests

# Run the server directly
OBSIDIAN_VAULT_PATH=/path/to/vault uv run python -m obsidian_vault_mcp

许可证

麻省理工学院

相关 MCP