obsidian-mcp

MCP 服务器，封装了官方的 Obsidian CLI，以便 LLM 智能体能够驱动运行中的 Obsidian 实例——读取/写入笔记、搜索、管理元数据、导航链接、运行插件等。

该服务器是一个轻量且全面的封装。每个工具都与一个 obsidian CLI 命令 1:1 对应。

前提条件

1. Obsidian 必须处于运行状态。 CLI 通过 IPC 与实时运行的应用程序通信；它不会直接读取磁盘上的库。

2. 注册 CLI 二进制文件。 在 Obsidian 中：设置 → 常规 → 命令行界面 → 注册 CLI。Obsidian 会将 obsidian 添加到你的 PATH 中。

3. 验证：obsidian version 会打印 CLI 版本。

安装

根据你是想自行构建还是从 npm 获取预发布版本，有两种路径。

选项 A — 克隆并构建（当前可用）

克隆仓库并在本地构建，然后将 Claude Code 指向构建后的文件：

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

使用 Claude Code 注册它（一条命令）：

# Add (user scope — available across all projects)
claude mcp add -s user obsidian -- node /absolute/path/to/obsidian-mcp/dist/index.js

# Remove
claude mcp remove obsidian

# List configured servers
claude mcp list

-s user 将其注册到你的整个用户账户。使用 -s project 将其提交到仓库的 .mcp.json 中，或者使用 -s local 仅用于当前项目（默认）。

或者手动将其写入 .mcp.json：

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

选项 B — 从 npm 安装（无需构建）

前提条件： 该包必须已经发布到 npm。维护者通过 npm publish 发布一次；所有后续用户通过 npx 自动获取。如果你 fork 了此仓库并希望在自己的作用域下使用此流程，请将 package.json 中的 name 更改为 @<你的-npm-用户名>/obsidian-mcp，然后执行 npm publish。

发布后，无需克隆或构建：

claude mcp add -s user obsidian -- npx -y @yuchichang/obsidian-mcp

或者在 .mcp.json / Claude Desktop 的 claude_desktop_config.json 中配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@yuchichang/obsidian-mcp"]
    }
  }
}

覆盖 CLI 路径

如果 obsidian 不在 PATH 中，请设置 OBSIDIAN_CLI 环境变量。适用于上述两种安装路径：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_CLI": "C:/Users/you/AppData/Local/Obsidian/obsidian.cmd"
      }
    }
  }
}

工具

库与文件

前置元数据 (Frontmatter)

搜索

标签与链接

日记

插件

开发者 / 高级功能

元信息

约定

• 定位笔记 — 文件定位工具接受以下任一参数：

  • file — Wiki 链接风格的笔记名称（例如 "My Note"），或

  • path — 相对于库的文件路径（例如 "Folder/My Note.md"）。

• 多库设置 — 每个工具都接受一个可选的 vault 参数。如果省略，则使用最近聚焦的库。

• 输出格式 — 列表/搜索/元数据工具默认使用 JSON，以便于机器解析。

敏感操作与用户确认

以下工具受到用户确认步骤的保护：

确认机制的工作方式：

1. MCP 启发式确认（首选）。 如果连接的客户端支持 elicitation 能力（Claude Code 支持），服务器会发送 elicitation/create 请求，客户端会向用户显示一个包含具体操作和目标的 Proceed? 提示。只有 accept + confirm: true 才会继续执行。

2. 显式 confirm: true 参数。 每个敏感工具的输入模式都包含一个可选的 confirm: boolean。传递 confirm: true 会跳过启发式提示——仅在调用者已获得用户批准时使用此参数。

3. 拒绝回退。 如果客户端不支持启发式确认且未提供 confirm: true，工具将返回一个 isError 结果，说明操作名称并指示调用者使用 confirm: true 重试。

批量/自动化绕过

OBSIDIAN_MCP_AUTO_CONFIRM=1

设置此环境变量（在 MCP 客户端的 env 块中）以跳过所有确认提示。仅在完全受信任的自动化环境中使用。

长内容与 argv 限制

Obsidian CLI 尚不支持从 stdin 或文件读取参数值——每个值都必须通过命令行传递。这与平台限制冲突：

为了安全起见，服务器会自动分块长写入内容：

拆分尽可能在行边界处进行；超大的单行内容会回退到 UTF-8 安全的字符边界。重组后的内容与原始内容字节完全一致。

配置单次调用的字节阈值（默认值：Windows 上为 6,000，其他平台为 100,000）：

OBSIDIAN_MCP_MAX_ARG_BYTES=4000

如果多块写入中间的某一块失败，服务器会返回 isError 并附带明确消息，说明哪些块已写入磁盘，以便调用者进行恢复。

开发

npm run dev      # tsc --watch
npm run inspect  # launch MCP Inspector against the built server
node scripts/smoke-test.mjs   # initialize + tools/list smoke test

工作原理

runObsidian() (src/exec.ts) 对参数进行 shell 转义，通过 child_process.exec 调用 obsidian 二进制文件，并解析 stdout。大多数读取类工具请求 format=json；结果被解析为 structuredContent 以供消费结构化工具输出的客户端使用，同时在 content 中返回文本表示。

工具注册表位于 src/tools.ts — 添加新的封装命令只需在那里增加一个条目。

参考

• Obsidian CLI: https://obsidian.md/help/cli

• MCP 规范: https://modelcontextprotocol.io