obsidian-cli-mcp

一个MCP服务器，让Claude和其他MCP客户端通过官方Obsidian CLI（Obsidian 1.12+）完全控制正在运行的Obsidian仓库，并在正确性允许的情况下使用快速直接的文件系统读取。

姊妹项目：things-for-mac-mcp。

有何不同？

大多数Obsidian MCP服务器要么与社区REST插件通信，要么直接读取仓库文件夹。前者需要安装并信任一个插件。后者在移动或重命名文件时会悄悄破坏wiki链接，因为只有Obsidian知道指向它的每个链接、别名和嵌入。

此服务器按能力路由每个操作：

其架构与姊妹项目完全一致：

分割规则：批量读取走文件系统（需要吞吐量），任何涉及移动、重命名、删除或依赖链接解析与应用状态的操作走CLI（需要Obsidian的知识）。文件系统适配器在结构上不能修改仓库，它完全不导出写入功能。

要求

• macOS、Windows或Linux桌面版，Obsidian 1.12或更高版本

• 已启用Obsidian CLI：Obsidian → 设置 → 通用 → 命令行界面

• Obsidian必须正在运行。 CLI是应用的客户端，不是独立二进制文件。仅限桌面，不支持移动端。

• Node.js 18或更高版本

安装

git clone https://github.com/jabaho9523/obsidian-cli-mcp.git
cd obsidian-cli-mcp
npm install
npm run build

连接到MCP客户端

Claude（桌面版 / Code）

添加到 claude_desktop_config.json（Claude Desktop）或运行 claude mcp add（Claude Code）：

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/obsidian-cli-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT": "YourVaultName"
      }
    }
  }
}

使用 node 的绝对路径，不要只写单词。 GUI启动的应用不会继承你的shell PATH，因此 "command": "node" 在许多客户端中会静默失败。用 which node 找到你的路径。

如果你有多个仓库，设置 OBSIDIAN_VAULT。 否则CLI默认针对最后聚焦的仓库，这对于自动写入来说非常糟糕。只有一个仓库时，服务器会在启动时自动固定它。

配置

安全护栏

三个层级，在生成二进制文件之前强制执行：

• 第1层，免费： 读取、搜索和增量写入（create_note、append_note、append_daily、set_property、update_task、capture）。

• 第2层，需要在工具调用中设置 confirm: true： delete_note、move_note、rename_note、remove_property、run_obsidian_command，以及通过透传：history:restore、publish:*、plugin:enable/disable/reload、theme:*、snippet:*、sync、sync:restore、reload、template:insert、workspace:save/delete。任何带有 overwrite 或 permanent 标志的调用也会升级到第2层。

• 第3层，除非服务器以 OBSIDIAN_MCP_ALLOW_DANGEROUS=1 运行，否则被阻止： eval、restart、plugin:install、plugin:uninstall、plugins:restrict、devtools、dev:cdp、dev:debug、dev:mobile，以及带有 permanent: true 的 delete_note。

一个诚实的说明。第2层是防止意外调用的减速带，而非安全措施：调用模型可以自行设置 confirm: true。第3层是真正的边界，因为只有配置服务器环境的人才能解锁它。如果你将自主代理指向一个你关心的仓库，请使用 OBSIDIAN_MCP_READONLY=1 运行，这会在分派前拒绝所有修改命令，无论层级如何。

安全的移动和重命名

此项目中最重要的一条规则：文件永远不会通过文件系统移动、重命名或删除。 Obsidian在执行操作时会更新仓库中的每个wiki链接。单纯的 mv 不会。

之前，Projects/Roadmap.md 从三个笔记中被链接：

Weekly Review.md:   Progress on [[Roadmap]] is on track.
Team Notes.md:      See [[Roadmap#Q3]] for the plan.
Index.md:           - [[Roadmap|2026 roadmap]]

在使用 to: "Archive/2026 Roadmap.md" 执行 move_note 之后：

Weekly Review.md:   Progress on [[2026 Roadmap]] is on track.
Team Notes.md:      See [[2026 Roadmap#Q3]] for the plan.
Index.md:           - [[2026 Roadmap|2026 roadmap]]

所有三个链接都已更新，包括标题锚点和别名，因为Obsidian执行了移动。文件系统的移动会导致三个链接断裂且无错误提示。

为什么混合？性能原理

每次CLI调用都是通过正在运行的Obsidian应用进行一次完整的IPC往返。这虽然正确但较慢：通过 obsidian read 读取2000篇笔记需要2000次往返，需要几分钟的墙钟时间。从磁盘读取则是一次目录遍历，在任何SSD上都远低于1秒。

因此，批量读取（搜索、列表、标签和属性扫描、导出、摘要）走文件系统，CLI保留用于只有Obsidian才能回答的操作（链接、别名、Bases、模板、应用状态）以及所有写入操作。要比较你自己的仓库，可以将 search_notes 与透传 obsidian_cli 配合 ["search", "query=..."] 计时。

故障排除

"Obsidian未运行。" 最常见的失败原因。CLI需要应用打开并完全加载。启动Obsidian并重试。

"找不到Obsidian CLI二进制文件。" 在Obsidian设置 → 通用 → 命令行界面中启用CLI，或者将 OBSIDIAN_BIN 指向该二进制文件。

第一条命令超时。 冷启动Obsidian可能超过默认的20秒。提高 OBSIDIAN_MCP_TIMEOUT。

笔记读取为缺失，或服务器频繁回退到CLI。 如果你的仓库位于iCloud且开启了“优化Mac存储”，已驱逐的文件仅作为 .name.icloud 存根存在。服务器会检测到这些文件，并通过Obsidian读取它们（这会重新下载），而不是报告空笔记。批量扫描会跳过已驱逐的文件，并在输出中说明。

写入操作进入错误的仓库。 你有多个仓库且未设置 OBSIDIAN_VAULT。服务器会在启动时在stderr上对此发出警告。固定一个。

工具未在客户端中出现。 检查客户端的MCP日志，并检查上述的绝对node路径问题。

保持更新

git pull && npm install && npm run build

服务器在启动时检查更新，最多每24小时一次，将结果缓存在 ~/.config/obsidian-cli-mcp/update-check.json。离线时静默失败，并在存在更新版本时打印一行stderr信息。

工具（共39个）

读取工具（18个）

写入工具（16个）

所有写入操作都通过CLI进行。每个都需要显式的 file 或 path 目标，都不允许回退到当前活动文件。

run_obsidian_command 是服务器中最宽的门：它能访问所有命令面板操作，包括社区插件注册的。它被有意暴露，并在等级 2 进行防护。

工作流工具 (4)

逃生舱 (1)

MCP 资源

客户端对资源的支持各不相同，Claude Desktop 目前不展示它们。

MCP 提示

架构

src/
├── index.ts              MCP server entry, stdio transport
├── config.ts             Environment configuration
├── adapters/
│   ├── cli.ts            execFile wrapper, vault injection, error contract
│   └── filesystem.ts     Read-only vault access, iCloud stub detection
├── tools/
│   ├── common.ts         Shared note loading with CLI fallback
│   ├── read.ts           18 read tools
│   ├── write.ts          16 write tools
│   ├── workflow.ts       4 composite tools
│   └── passthrough.ts    obsidian_cli escape hatch
├── resources/
│   └── vault.ts          MCP resources
├── prompts/
│   └── workflows.ts      MCP prompts
└── utils/
    ├── guardrails.ts     Tier policy, readonly allowlist
    ├── markdown.ts       Frontmatter, headings, tags, word counts
    ├── output.ts         Truncation at 60,000 characters
    └── update-check.ts   Daily update check

测试针对一个存根二进制文件运行，该文件扫描其完整 argv，并可被指示失败、挂起或输出过大内容，因此整个测试套件在未安装 Obsidian 的情况下也能通过：

npm test

支持

问题和功能请求：GitHub issues。

作者的其他作品

• things-for-mac-mcp，Things 3 的姊妹 MCP 服务器

许可证

MIT