Obsidian CLI MCP Server

使用 TypeScript 实现的 stdio MCP Server，通过 Obsidian 官方 CLI 为 Claude Code、Codex 等 AI Agent 提供 Vault 操作能力。

本项目不直接读写 Vault 文件，也不通过 shell 拼接命令。所有操作均以参数数组调用 Obsidian CLI，并提供 Vault 锁定、命令权限、超时、输出限制及跨进程串行保护。

功能

• 查询 Obsidian 及 CLI 状态
• 列出 Vault 内的文件和文件夹
• 读取、创建、覆盖、追加和前置写入笔记
• 将大段 Markdown 自动拆成 UTF-8 安全块写入
• 搜索笔记及匹配上下文
• 调用属性、链接、任务、模板、历史、插件和开发者命令
• 按配置允许删除、command、eval 等高权限操作
• 将 Server 硬锁定到指定 Vault
• 串行处理多个 Agent 或并发 MCP 请求

调用链如下：

Claude Code / Codex
        │ stdio MCP
        ▼
Obsidian CLI MCP Server
        │ FIFO + 跨进程锁
        ▼
Obsidian.com / obsidian
        │ IPC
        ▼
正在运行的 Obsidian

前置条件

• Node.js 20 或更高版本
• Obsidian 1.12.7 或更高版本的安装器
• 在 Obsidian 的“设置 → 常规”中启用“命令行接口”
• 调用时保持 Obsidian 桌面端运行
• 目标 Vault 已由 Obsidian 打开或管理

Windows 使用安装目录中的 Obsidian.com 作为终端重定向器。升级安装器后，应重新启用命令行接口并重启终端。

先验证官方 CLI：

obsidian version
obsidian vaults verbose

安装与构建

Set-Location D:\Document\MyMCP\ObsidianCli
npm install
npm run check
npm test
npm run build

构建入口为：

D:\Document\MyMCP\ObsidianCli\dist\index.js

修改 TypeScript 源码后必须重新执行 npm run build，并重启 MCP 客户端会话。

配置 Claude Code

在 Vault 或 Claude Code 项目根目录创建 .mcp.json。下面是锁定到 Dance 且允许全部 Obsidian CLI 能力的配置：

{
  "mcpServers": {
    "obsidian-cli": {
      "command": "node",
      "args": [
        "D:\\Document\\MyMCP\\ObsidianCli\\dist\\index.js"
      ],
      "env": {
        "OBSIDIAN_CLI_COMMAND": "D:\\Apps\\Common\\Obsidian\\Obsidian.com",
        "OBSIDIAN_DEFAULT_VAULT": "Dance",
        "OBSIDIAN_LOCKED_VAULT": "Dance",
        "OBSIDIAN_CLI_ALLOW_UNSAFE": "true",
        "OBSIDIAN_CLI_EXTRA_COMMANDS": "*"
      }
    }
  }
}

MCP 配置中的环境变量值必须全部是字符串。特别是应写成 "true"，不能写成 JSON 布尔值 true，否则 Claude Code 会忽略整个 Server 配置。

从项目根目录验证：

claude mcp list
claude mcp get obsidian-cli

预期状态：

obsidian-cli ... ✓ Connected

修改 .mcp.json 或重新构建 Server 后，应退出并重新启动 Claude Code。

配置 Codex

在受信任的项目中创建 .codex/config.toml：

[mcp_servers.obsidian-cli]
command = "node"
args = ['D:\Document\MyMCP\ObsidianCli\dist\index.js']
cwd = 'D:\Workspace\Ob\Dance\Dance'
enabled = true
required = true
startup_timeout_sec = 30
tool_timeout_sec = 60
default_tools_approval_mode = "approve"

[mcp_servers.obsidian-cli.env]
OBSIDIAN_CLI_COMMAND = 'D:\Apps\Common\Obsidian\Obsidian.com'
OBSIDIAN_DEFAULT_VAULT = "Dance"
OBSIDIAN_LOCKED_VAULT = "Dance"
OBSIDIAN_CLI_ALLOW_UNSAFE = "true"
OBSIDIAN_CLI_EXTRA_COMMANDS = "*"

Codex 只会为受信任项目加载项目级 .codex/config.toml。修改配置或重新构建后，以目标 Vault 为工作区新建 Codex 线程。

配合项目 Skill

MCP Server 负责提供操作能力，Skill 负责规定 Agent 的知识管理流程。当前 Dance 项目分别使用：

.claude/skills/curate-dance-vault/SKILL.md
.agents/skills/curate-dance-vault/SKILL.md

Claude Code 与 Codex 使用相同 Skill 内容，约束 inbox、atlas、workspace、archive、system 的数据流，并要求优先使用本 MCP，而不是 shell 文件操作。

MCP 工具

工具	主要输入	用途
obsidian_status	无	查询 Obsidian 版本及 CLI 连通性
obsidian_help	command?	查询总帮助或指定命令帮助
obsidian_list	type、vault?、folder?、extension?	列出 Vault、文件或文件夹
obsidian_read_note	path、vault?	按 Vault 相对路径读取笔记
obsidian_write_note	path、content、mode、overwrite、vault?	创建、追加或前置写入笔记
obsidian_search	query、path?、limit?、context、format、vault?	搜索笔记内容
obsidian_cli	command、parameters、flags、vault?	执行其他允许的 Obsidian CLI 命令

obsidian_write_note.mode 支持：

• create
• append
• prepend

obsidian_write_note 会把正文拆成最多 1,024 UTF-8 字节的块，并在一个不可交错的 CLI 批次中完成写入。调用方仍只需提交一次完整正文。

obsidian_cli 的参数格式：

{
  "command": "move",
  "parameters": {
    "path": "inbox/source.md",
    "to": "archive/source.md"
  },
  "flags": []
}

Server 会将 Vault 参数放在命令之前，并将普通参数转换为 key=value。Obsidian 的普通布尔开关使用裸 flag，例如 overwrite、verbose；全局复制选项使用 --copy。

环境变量

环境变量	默认值	说明
OBSIDIAN_CLI_COMMAND	obsidian	CLI 可执行文件名或绝对路径
OBSIDIAN_DEFAULT_VAULT	未设置	工具调用未指定 Vault 时使用的默认值
OBSIDIAN_LOCKED_VAULT	未设置	将 Server 硬锁定到指定 Vault，并禁止枚举所有 Vault
OBSIDIAN_CLI_TIMEOUT_MS	30000	单个进程的执行超时，范围 1–300 秒
OBSIDIAN_CLI_MAX_OUTPUT_BYTES	1048576	单次调用最大输出，最高 10 MiB
OBSIDIAN_CLI_ALLOW_UNSAFE	false	允许已知高影响命令
OBSIDIAN_CLI_EXTRA_COMMANDS	未设置	额外命令名，逗号分隔；* 表示允许全部合法命令名

同时设置默认和锁定 Vault 时，两者必须一致，否则 Server 拒绝启动。

推荐的受限配置

OBSIDIAN_DEFAULT_VAULT=Dance
OBSIDIAN_LOCKED_VAULT=Dance
OBSIDIAN_CLI_ALLOW_UNSAFE=false

完全信任配置

OBSIDIAN_DEFAULT_VAULT=Dance
OBSIDIAN_LOCKED_VAULT=Dance
OBSIDIAN_CLI_ALLOW_UNSAFE=true
OBSIDIAN_CLI_EXTRA_COMMANDS=*

完全信任配置允许 delete、eval、command、插件管理、发布、恢复、主题及开发者命令，但仍不会把输入交给操作系统 shell。eval 和插件命令本身仍可能对 Obsidian 应用或 Vault 产生广泛影响。

安全与并发模型

命令安全

• 使用 spawn(executable, argv, { shell: false })
• 校验命令、参数名和 flag 格式
• 默认使用安全命令白名单
• 高影响命令需要 OBSIDIAN_CLI_ALLOW_UNSAFE=true
• 未知或插件命令需要显式加入额外白名单，或设置 OBSIDIAN_CLI_EXTRA_COMMANDS=*
• 限制进程执行时间和输出大小
• 拒绝超过安全请求头大小的通用 CLI 调用；长正文必须使用 obsidian_write_note

Vault 隔离

设置 OBSIDIAN_LOCKED_VAULT 后：

• 所有未指定 Vault 的命令自动使用锁定值
• 显式指定其他 Vault 会返回错误
• obsidian_list type=vaults 和通用 vaults 命令被禁用

Vault 锁定只约束通过本 Server 执行的命令。高权限的 Obsidian 应用级操作，例如插件安装或 eval，仍需由可信 Agent 使用。

并发保护

Windows Obsidian.com 通过 IPC 与 Obsidian 主进程通信。多个 CLI 进程同时发送消息可能导致主进程 JSON 边界损坏。

Server 使用两层保护：

1. 每个 MCP Server 内部的 FIFO Promise 队列。
2. 临时目录中的跨进程锁，并使用心跳与失效锁恢复。

因此 Claude Code、Codex 和并发 MCP 工具调用会依次访问 Obsidian CLI。直接在终端运行的 obsidian 命令不会经过此锁，Agent 工作期间不要在其他终端并行执行大量 CLI 命令。

故障排查

Claude Code 显示 No MCP servers configured

检查：

1. Claude Code 是否从包含 .mcp.json 的项目根目录启动。
2. .mcp.json 是否为有效 JSON。
3. env 下所有值是否都是字符串。
4. 项目 MCP Server 是否已获准启用。

运行：

claude mcp list
claude mcp get obsidian-cli

修改后重启 Claude Code。

Obsidian 主进程出现 Unexpected token ... is not valid JSON

这表示 Windows CLI IPC 收到了损坏的 JSON 请求头。已确认的触发因素包括单次 content= 正文过大，以及多个 CLI 进程并行发送消息。当前 Server 会自动分块正文、限制通用请求大小并串行执行。

处理步骤：

1. 确认已使用包含 FIFO 和跨进程锁的最新构建。
2. 执行 npm run build。
3. 完全退出 Claude Code、Codex 和 Obsidian。
4. 先重新启动 Obsidian，再启动 Agent。
5. 不要从其他终端并行运行 Obsidian CLI。

Agent 不应在 MCP 写入失败后降级到系统 Write 或 shell；这会绕过 Obsidian 和 Skill 的数据流规则。

跨进程锁异常退出后会自动恢复失效锁。

CLI 提示找不到 Obsidian

The CLI is unable to find Obsidian.

确认：

• Obsidian 正在运行
• 安装器为 1.12.7+
• 命令行接口已重新启用
• MCP 进程与 Obsidian 运行在同一 Windows 用户和会话中
• OBSIDIAN_CLI_COMMAND 指向正确的 Obsidian.com

修改源码后行为没有变化

MCP 客户端运行的是 dist/，不是 src/。执行：

npm run check
npm test
npm run build

然后重启 Claude Code/Codex 会话。

开发

npm run dev

项目结构：

src/
  commands.ts  命令白名单、参数与 flag 构造
  config.ts    环境变量解析和 Vault 锁定配置
  content.ts   UTF-8 安全正文分块
  runner.ts    进程执行、FIFO 与跨进程锁
  server.ts    MCP 工具注册
  index.ts     stdio 入口
test/
  commands.test.ts
  config.test.ts
  content.test.ts
  runner.test.ts
  server.test.ts

stdio 的标准输出专用于 MCP 协议；Server 日志只能写入标准错误。

验证

npm run check
npm test
npm run build

当前测试覆盖：

• 参数构造与 shell 注入边界
• 安全、危险及通配命令权限
• Vault 锁定配置
• CLI 退出码、超时与输出限制
• 单进程及跨 Runner 串行执行
• MCP 工具发现

参考

• Obsidian CLI 官方文档
• Model Context Protocol
• Codex MCP 配置
• Codex 自定义与项目 Skill