obsidian-mcp

为 Claude（及任何 MCP 客户端）提供对您的 Obsidian 库的真正代理访问权限——包括图谱遍历、Dataview 查询、每日笔记感知等功能。

安装 · 工具 · 尝试提示词 · 对比分析 · 常见问题

大多数 Obsidian MCP 服务器仅暴露 read_file 和 write_file 就草草了事。而本项目将您的库视为一个知识图谱——您的 LLM 可以通过单次调用获取反向链接、正向链接、Dataview 查询、每日笔记以及多跳图谱遍历。

为什么选择本项目

当您打开 Claude Desktop，要求它查找笔记中的关联时，它通常会通过 read_file 一次读取一个笔记。但这并不是 Obsidian 用户思考笔记的方式。图谱本身才是价值所在——反向链接、传递性连接、标签、Dataview 类型元数据。本服务器将所有这些都作为一等工具暴露出来。

安装

您需要在 Obsidian 中安装 Local REST API 插件。从社区插件中安装并启用它，然后从其设置中复制 API 密钥。

Claude Desktop

将其添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "paste-your-key-here"
      }
    }
  }
}

重启 Claude Desktop。安装完成。

Claude Code

claude mcp add obsidian -e OBSIDIAN_API_KEY=paste-your-key-here -- npx -y obsidian-mcp

Cursor / Cline / Continue / Zed

任何兼容 MCP 的客户端均可使用。将其指向 npx -y obsidian-mcp 并在环境变量中设置 OBSIDIAN_API_KEY。

从源码安装

git clone https://github.com/yanxue06/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build
OBSIDIAN_API_KEY=... node dist/index.js

尝试提示词

在连接了服务器的 Claude Desktop 中尝试以下提示词：

为我所有关于分布式系统的笔记构建一个内容地图（MOC）。使用 traverse_graph 从 "Distributed systems.md" 开始，深度设为 2，然后按主题对邻居节点进行分组，并将 MOC 写入 MOCs/Distributed systems MOC.md。

查找所有标记为 #project 且 status != "done" 且截止日期在本周的笔记。使用 query_dataview。

我今天的每日笔记里写了什么？有没有什么我从昨天的笔记中忘记跟进的事项？

查找 Inbox/ 中所有孤立笔记。针对每一篇，根据其内容和现有标签建议它应该归类到哪里。

我要将 "Atomic notes.md" 重命名为 "Evergreen notes.md"。请找出所有链接到它的笔记，并告诉我哪些需要更新。

从 "Working memory.md" 开始遍历 2 跳，告诉我哪些笔记是我关于注意力思考的核心。

工具

共 15 个工具。差异化工具已加粗。

读取

搜索与图谱

写入

对比分析

配置

所有配置均通过环境变量完成——在您的 MCP 客户端配置中设置它们。

工作原理

┌──────────────┐     stdio (MCP)      ┌──────────────┐    HTTPS     ┌──────────────────┐
│ Claude / IDE │ ───────────────────► │ obsidian-mcp │ ───────────► │  Local REST API  │ ──► Vault
└──────────────┘                      └──────────────┘              │ (Obsidian plugin)│
                                                                    └──────────────────┘

obsidian-mcp 是 Local REST API 插件 的轻量级封装。该插件在 Obsidian 内部运行一个 HTTPS 服务器，提供对库的完全访问权限；本服务器将该接口适配为 MCP 协议，并添加了 Obsidian REST API 未直接暴露的图谱感知工具（反向链接、多跳遍历、孤立节点检测）。

一切都在本地运行。除了您的 MCP 客户端向其模型提供商发出的请求外，没有任何数据离开您的机器——且您可以控制这些请求。

常见问题

我需要安装 Obsidian 插件吗？ 是的——需要 Local REST API 插件。这是从外部与运行中的库进行通信的唯一合理方式。安装后，obsidian-mcp 本身作为由您的 MCP 客户端启动的独立 Node 进程运行；您无需为此在 Obsidian 中安装其他插件。

如果 Obsidian 关闭了，它还能工作吗？ 不能。Local REST API 在 Obsidian 内部运行，因此应用程序必须保持打开状态。

它支持多个库吗？ 一个服务器实例指向一个正在运行的 Obsidian 实例。如果您经常切换库，请运行多个 MCP 服务器条目（不同的名称 + 不同的端口）。

为什么默认使用 OBSIDIAN_VERIFY_TLS=false 的 HTTPS？ 该插件附带一个自签名证书。流量仅限于本地回环 (127.0.0.1)，因此验证只会增加麻烦而没有实际的安全收益。如果您已替换证书，请设置该标志。

这安全吗？ MCP 服务器赋予模型 API 密钥所授予的任何权限。模型愿意删除的任何内容，它都可以删除。请像对待任何具有文件写入权限的代理一样对待它——在执行批量操作之前，请务必审查它即将执行的操作。

路线图

• [ ] 基于嵌入的语义搜索（目前通过插件仅支持关键词搜索）

• [ ] 工作区切换 / 多库路由

• [ ] 只读安全模式（不注册写入工具）

• [ ] 资源订阅（笔记更改时推送更新）

• [ ] Smithery / mcp-get 注册表提交

欢迎提交 PR。请参阅 CONTRIBUTING.md。

致谢

• Local REST API 作者 @coddingtonbear —— 整个项目均基于此构建。

• Anthropic 的 Model Context Protocol 团队。

许可证

MIT — 详见 LICENSE。