obsidian-cli-mcp

obsidian-cli-mcp 是一个用于官方 Obsidian CLI 的 MCP 服务器。它将 Obsidian 仓库搜索、笔记、任务、文件、链接和原生 Canvas 操作暴露给 MCP 客户端。该服务器不会替代 Obsidian：CLI 会将请求转发给正在运行的 Obsidian 桌面应用。

默认传输方式是本地 stdio。远程 Streamable HTTP 作为高级、单独安全配置可用；本地使用不需要它。

要求

• 安装了 Obsidian Desktop 并正在运行的 macOS。

• 在 Obsidian 中启用官方 Obsidian CLI：设置 → 通用 → 命令行界面，然后在你的 PATH 中注册 obsidian。

• 运行已发布包需要 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/obsidian-cli-mcp@0.4.1 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/obsidian-cli-mcp@0.4.1",
        "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。

工具表面

默认服务器提供 42 个常规工具：

• 读取：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。

所有修改工具都接受 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