MCP 服务器，封装了官方的 Obsidian CLI，以便 LLM 智能体能够驱动运行中的 Obsidian 实例——读取/写入笔记、搜索、管理元数据、导航链接、运行插件等。
该服务器是一个轻量且全面的封装。每个工具都与一个 obsidian CLI 命令 1:1 对应。
Obsidian 必须处于运行状态。 CLI 通过 IPC 与实时运行的应用程序通信；它不会直接读取磁盘上的库。
注册 CLI 二进制文件。 在 Obsidian 中：设置 → 常规 → 命令行界面 → 注册 CLI。Obsidian 会将 obsidian 添加到你的 PATH 中。
验证：obsidian version 会打印 CLI 版本。
Related MCP server: Vault Cortex Obsidian MCP Server
根据你是想自行构建还是从 npm 获取预发布版本，有两种路径。
克隆仓库并在本地构建，然后将 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"]
}
}
}前提条件： 该包必须已经发布到 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"]
}
}
}如果 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"
}
}
}
}工具 | 封装命令 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
工具 | 封装命令 |
|
|
|
|
|
|
工具 | 封装命令 |
|
|
|
|
工具 | 封装命令 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
工具 | 封装命令 |
|
|
|
|
|
|
工具 | 封装命令 |
|
|
|
|
|
|
|
|
工具 | 封装命令 | 说明 |
|
| ⚠️ 在 Obsidian 内部运行任意 JS。视为破坏性操作。 |
|
| 返回 base64 PNG。 |
|
| |
|
|
工具 | 封装命令 |
|
|
|
|
定位笔记 — 文件定位工具接受以下任一参数：
file — Wiki 链接风格的笔记名称（例如 "My Note"），或
path — 相对于库的文件路径（例如 "Folder/My Note.md"）。
多库设置 — 每个工具都接受一个可选的 vault 参数。如果省略，则使用最近聚焦的库。
输出格式 — 列表/搜索/元数据工具默认使用 JSON，以便于机器解析。
以下工具受到用户确认步骤的保护：
工具 | 原因 |
| 删除数据（特别是使用 |
| 重命名 + 重写整个库中的 Wiki 链接。 |
| 删除前置元数据。 |
| 批量重写所有笔记中的标签。 |
| 授予社区插件代码执行权限。 |
| 在 Obsidian 内部运行任意 JavaScript。 |
确认机制的工作方式：
MCP 启发式确认（首选）。 如果连接的客户端支持 elicitation 能力（Claude Code 支持），服务器会发送 elicitation/create 请求，客户端会向用户显示一个包含具体操作和目标的 Proceed? 提示。只有 accept + confirm: true 才会继续执行。
显式 confirm: true 参数。 每个敏感工具的输入模式都包含一个可选的 confirm: boolean。传递 confirm: true 会跳过启发式提示——仅在调用者已获得用户批准时使用此参数。
拒绝回退。 如果客户端不支持启发式确认且未提供 confirm: true，工具将返回一个 isError 结果，说明操作名称并指示调用者使用 confirm: true 重试。
OBSIDIAN_MCP_AUTO_CONFIRM=1设置此环境变量（在 MCP 客户端的 env 块中）以跳过所有确认提示。仅在完全受信任的自动化环境中使用。
Obsidian CLI 尚不支持从 stdin 或文件读取参数值——每个值都必须通过命令行传递。这与平台限制冲突：
平台 | 实际命令行限制 |
Windows (cmd.exe) | 总计约 8,191 字符 |
macOS / Linux |
|
为了安全起见，服务器会自动分块长写入内容：
工具 | 分块策略 |
| 第一块通过 |
| 顺序调用 |
| 以相反顺序调用 |
| 解析日记路径，然后进行分块追加。 |
| 不分块 — JS 无法拆分。返回错误，建议使用“通过笔记运行脚本”的变通方法。 |
拆分尽可能在行边界处进行；超大的单行内容会回退到 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 testrunObsidian() (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
Appends markdown content to the end of an existing note.
Inputs: content (required), vault, file, path.
Creates a new note. name is the path (relative to the vault root), with or without the .md extension.
Inputs: name (required), vault, content, template.
Appends content to today's daily note (creates it if missing).
Inputs: content (required), vault.
Returns the file path of today's daily note.
Inputs: vault.
Returns the content of today's daily note.
Inputs: vault.
Moves a note to the system trash. Set permanent: true to bypass trash and delete immediately (irreversible).
Inputs: vault, file, path, permanent, +1 more.
Returns recent console messages from Obsidian DevTools.
Inputs: vault.
Returns recent JS errors from the Obsidian DevTools console.
Inputs: vault.
Returns a base64-encoded PNG screenshot of the running Obsidian window.
Inputs: vault.
Disables a community plugin by id.
Inputs: id (required), vault.
Enables a community plugin by id.
Inputs: id (required), vault, confirm.
Runs arbitrary JavaScript inside the running Obsidian instance with access to the app object. DANGEROUS: can read/modify any vault data and execute side effects. Use only when no narrower tool fits.
Inputs: code (required), vault, confirm.
Lists every note tagged with the given tag.
Inputs: tag (required), vault.
Returns notes that link to the target note.
Inputs: vault, file, path.
Returns the outgoing wikilinks from a note.
Inputs: vault, file, path.
Returns metadata for a note (frontmatter, tags, links, file stats) as JSON.
Inputs: vault, file, path.
Returns the YAML frontmatter properties of a note as JSON.
Inputs: vault, file, path.
Shows the underlying obsidian help output — useful when a command behaves unexpectedly.
Inputs: all.
Lists every note in the vault. Returns JSON by default. Useful as a first step to discover what exists.
Inputs: vault, format.
Displays the vault folder structure as a tree.
Inputs: vault, format.
Finds notes that have no incoming wikilinks.
Inputs: vault.
Lists installed community + core plugins with enabled state.
Inputs: vault.
Lists every tag used in the vault, with usage counts.
Inputs: vault.
Finds wikilinks that point to non-existent notes.
Inputs: vault.
Moves or renames a note. Wikilinks across the vault are updated automatically.
Inputs: to (required), vault, file, path, +1 more.
Inserts content near the top of a note (after frontmatter, if present).
Inputs: content (required), vault, file, path.
Returns the full markdown content of a note.
Inputs: vault, file, path.
Reloads a plugin's code (useful during plugin development).
Inputs: id (required), vault.
Removes a frontmatter property from a note.
Inputs: name (required), vault, file, path, +1 more.
Renames a tag across every note in the vault.
Inputs: old (required), new (required), vault, confirm.
Full-text search across the vault. Returns matching files.
Inputs: query (required), vault, limit.
Full-text search that returns surrounding lines of context for each hit.
Inputs: query (required), vault, limit.
Sets a frontmatter property on a note. Creates the frontmatter block if missing.
Inputs: name (required), value (required), vault, file, +1 more.
Returns the version of the Obsidian CLI binary in use.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Scored across 34 tools
Most tools have distinct purposes, but there is some potential confusion between obsidian_search and obsidian_search_context, and between obsidian_get_backlinks and obsidian_get_links. Overall, descriptions are clear enough for an agent to differentiate.
All tools follow a consistent 'obsidian_verb_noun' snake_case pattern, making it predictable and easy to infer function from name.
With 34 tools, the server is over-scoped for typical MCP usage. While it covers many aspects of Obsidian, the high number suggests potential for splitting into specialized servers, and many tools (e.g., development utilities) may be unnecessary for most agents.
The tool set covers core note operations, search, tags, links, and daily notes well, but lacks explicit tools for creating folders, deleting tags, or handling attachments, leaving notable gaps in domain coverage.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…