Obsidian CLI MCP

obsidian-cli-mcp

obsidian-cli-mcp 是面向官方 Obsidian CLI 的 MCP 服务。它向 MCP 客户端提供 Obsidian 知识库搜索、笔记、任务、文件、链接和原生 Canvas 操作。该服务不会取代 Obsidian：CLI 会将请求转发给正在运行的 Obsidian 桌面应用。

默认传输方式为本地 stdio。远程 Streamable HTTP 可作为高级选项使用，但需单独配置安全措施；本地使用不需要此方式。

要求

• 安装并运行 Obsidian Desktop 的 macOS。
• 在 Obsidian 中启用官方 Obsidian CLI：设置 → 通用 → 命令行界面，然后将 obsidian 注册到 PATH 中。
• Node.js 18 或更高版本，用于运行已发布的软件包。只有在构建或开发此源代码检出版本时才需要 Bun。

此项目需要桌面 CLI。不支持 obsidian-headless。 使用 MCP 服务期间，Obsidian 应用必须保持打开。

请先检查 Obsidian 端：

command -v obsidian
obsidian version
obsidian vault

使用 npm 快速开始

从任意目录启动已发布的 v0.4.1 软件包：

npx --yes --package=@dariuscodes/[email protected] obsidian-cli-mcp

此命令通过 stdio 使用 MCP 通信，并等待 MCP 客户端连接。它不会向终端输出协议数据。诊断信息会输出到 stderr。

如需使用源代码检出版本：

git clone https://github.com/DariusCorvus/obsidian-cli-mcp.git
cd obsidian-cli-mcp
bun install --frozen-lockfile
bun run build
node dist/main.js

本地默认配置不需要知识库名称、知识库路径、令牌、Cloudflare 账户、LaunchAgent 或配置文件。服务会使用 Obsidian 通过官方 CLI 提供的活动知识库。

连接 MCP 客户端

对于接受 mcpServers 配置的客户端，请使用 npm 命令：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=@dariuscodes/[email protected]",
        "obsidian-cli-mcp"
      ]
    }
  }
}

如果客户端无法继承 shell 的 PATH，请将 npx 替换为 command -v npx 输出的绝对路径。对于源代码检出版本，请使用 command: "node" 和 args: ["/absolute/path/to/obsidian-cli-mcp/dist/main.js"]。

更改 MCP 配置后，请重启客户端。首次使用时，建议按以下顺序操作：

1. 使用一个应当存在于知识库中的查询调用 vault_search，例如 { "query": "meeting", "limit": 10 }。

2. 将一个返回的路径传给 note_read，例如 { "path": "<path returned by vault_search>" }。

3. 应用安全的笔记修改前，先预览：

   {
     "name": "MCP smoke note",
     "content": "Created after reviewing the plan.",
     "dryRun": true
   }
   

   这是一次 note_create 调用。它会返回计划执行的操作和准确的 CLI 命令，但不会更改知识库。检查计划后，才使用 dryRun: false。dryRun 是预览功能，不是授权边界。

4. 对于 Canvas，先预览一个原生 Canvas 文件和一个文本节点：

   {
     "path": "MCP smoke.canvas",
     "nodes": [
       {
         "id": "hello",
         "type": "text",
         "x": 0,
         "y": 0,
         "width": 320,
         "height": 180,
         "text": "Hello from MCP"
       }
     ],
     "dryRun": true
   }
   

   这是一次 canvas_create 调用。检查计划后，如果要创建文件，请使用 dryRun: false 调用它。之后使用 canvas_read 检查原生 .canvas JSON。Canvas 工具会保留未知字段、验证节点和边的引用，并且不需要任意 eval。

配置与安全默认值

空配置或缺少配置均可用于普通 Obsidian 知识库。服务会从其工作目录发现可选的 .obsidianmcprc.yaml。对于工作目录不可预测的客户端，请将 OBSIDIAN_MCP_CONFIG 设置为明确的配置文件路径。

默认策略有意限制在本地范围内：

• v0.4.0 服务不提供通用的 obsidian_eval 工具。默认情况下，eval.enabled 为 false；少数安全操作使用的内部固定 eval 代码片段，并非用户提供 JavaScript 的逃逸入口。
• 在明确配置 imports.allowedRoots 之前，禁用从任意本地文件导入。绝不会获取 URL。
• 默认阻止 .obsidian、.git、.trash、.Trash、Trash 和 .DS_Store 路径片段。添加 paths.allow 可限定到更小的知识库区域，并添加针对项目的 paths.deny 前缀，以保护更敏感的内容。
• 修改操作提供 dryRun。file_delete 需要 confirm: true；note_delete 默认使用 Obsidian 垃圾箱。永久删除需要明确设置 delete.mode: hard。
• 默认关闭 Git 自动提交。

只读预设

当 MCP 客户端应仅检查知识库时，请使用显式允许列表：

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - file_read_binary_metadata
    - canvas_read

安全本地预设

默认配置带有安全的本地防护，但并非只读。若要显式设置安全的本地工具集，允许正常编辑笔记和创建 Canvas，同时不提供删除、文件导入、文件生命周期操作和任意求值：

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - canvas_read
    - canvas_create
    - canvas_upsert_nodes
    - canvas_upsert_edges
    - canvas_add_node
    - canvas_add_edge
    - canvas_auto_layout
    - canvas_open
    - note_create
    - note_append
    - note_set_frontmatter
    - note_replace_range
    - note_insert_at
    - note_replace
    - note_insert
    - daily_open
    - daily_append
    - task_create
    - task_update
delete:
  mode: trash
eval:
  enabled: false
imports:
  allowedRoots: []

完全可信的本地预设

省略 tools.allow，以开放完整的内置工具集，同时保留默认的受保护路径、移至废纸篓的删除方式、禁用的导入功能和禁用的 obsidian_eval。如需导入，请仅配置专用的本地源目录：

imports:
  allowedRoots:
    - /absolute/path/to/approved-imports
  maxBytes: 26214400
  collision: increment
delete:
  mode: trash
eval:
  enabled: false

所有字段请参阅 docs/configuration.md，笔记整理预设请参阅 examples/。

本地 stdio 与远程 HTTP

本地 stdio 会由 MCP 客户端直接启动一个服务进程。推荐使用此安装方式：无需监听套接字、远程身份验证、Cloudflare 配置或公共端点。

Streamable HTTP 是一种可选的高级模式，适用于无法使用本地 stdio 的客户端。它仅绑定到环回地址，并且必须通过 Cloudflare Access JWT 验证或强能力令牌才能启动。请将其置于 TLS、经过身份验证的反向代理或隧道之后；不要绑定到 0.0.0.0。通用高级配置及其安全权衡请参阅 docs/remote-cloudflare.md。

工具集

默认服务会公开 43 个常规工具：

• 读取：vault_search、note_read、note_list、vault_tags、 unresolved_links、tasks_list、note_diff、backlinks_get、 outlinks_get、file_read_binary_metadata、canvas_read。
• 写入和工作流：note_create、note_append、note_set_frontmatter、 daily_open、daily_append、note_replace_range、note_insert_at、 note_replace、note_insert、task_create、task_update、 note_transition。
• 文件和附件：file_import、attachment_import、note_attach、 attachment_embed、file_move、file_rename、file_delete、 note_rename、note_move、folder_create、note_delete。
• Canvas：canvas_create、canvas_upsert_nodes、canvas_upsert_edges、 canvas_remove、canvas_open、canvas_add_node、canvas_add_edge、 canvas_auto_layout。
• 批处理：vault_batch 运行已启用的读取操作，并通过 args.dryRun: true 预览已启用的修改操作；支持依赖门控、按稳定输入顺序返回结果，以及受限的 batch.maxParallelism（默认值为 4，最大值为 8）。

所有会修改内容的工具都接受 dryRun。工具注释会标明只读和破坏性操作，供兼容的 MCP 客户端使用。

限制和安全

Obsidian Desktop 必须正在运行，且已启用其官方 CLI，并且当前活动知识库必须可供该桌面会话使用。此服务不是沙盒，也不支持 obsidian-headless。

知识库内容是不可信数据。笔记、Canvas 文本、任务文本和搜索结果可能包含提示词注入指令；MCP 客户端应将其视为数据，绝不能仅仅因为工具返回了知识库中的指令就遵循它们。工具输出也可能包含敏感的知识库内容，因此只能连接你信任的客户端。

启用远程 HTTP、导入、硬删除或宽泛的修改允许列表之前，请阅读 SECURITY.md。请按照其中的说明私下报告安全问题。

开发和 CI

源码检出使用 Bun，而发布的 bin 在 Node 上运行：

bun install
bun run typecheck
bun test
bun run build:schema
bun run build
bun run smoke:stdio
git diff --check
npm pack --dry-run --json

离线 stdio 冒烟测试会验证构建后的包入口点、MCP 初始化、tools/list、预期的工具集，以及 obsidian_eval 不存在。真实的 Obsidian 冒烟测试单独进行，并要求用户会话中 Obsidian 正在运行：

OBSIDIAN_CLI_BINARY=obsidian \
  OBSIDIAN_MCP_CONFIG=/absolute/path/to/your/config.yaml \
  OBSIDIAN_MCP_VAULT="your-vault-name" \
  bun run smoke:live

GitHub Actions 仅运行离线检查；它不依赖 Obsidian Desktop，也不需要托管运行器上的真实知识库。

许可证

MIT