Obsidian MCP Server

Obsidian MCP

一个本地 Model Context Protocol 服务，让兼容 MCP 的助手能够安全地读取和修改明确配置的 Obsidian 库。

版本 2 默认同时支持 MCP 2026-07-28 和 2025 年代的客户端，并要求 Node.js 22 或更高版本。它直接处理 Markdown 文件，因此无需打开 Obsidian。旧版协议和 v1 位置参数路径兼容性已弃用，并会将精确的迁移说明打印到 stderr。

重要

MCP 客户端可以调用具有破坏性的工具。请备份重要库，仔细查看客户端的权限提示，并在并发编辑笔记时使用修订版本前置条件。

快速开始

需要 Node.js 22 或更高版本：

node --version # v22 or newer

使用 npx 运行，无需全局安装软件包。固定主版本可获取兼容的 2.x 更新，而不会自动升级到未来的主版本：

npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/vault

配置 MCP 客户端，通过 stdio 启动相同的命令：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/vault"]
    }
  }
}

或者，全局安装软件包，并使用 "command": "obsidian-mcp"，参数与之前相同，从 "serve" 开始：

npm install -g obsidian-mcp@2

每个库都必须已包含 .obsidian 目录，并且必须使用绝对路径进行配置。

两个协议时代的客户端都通过相同的工具定义提供服务。确认 MCP 客户端协商使用 2026-07-28 后，可通过在 args 中添加 "--legacy", "reject"，选择仅支持现代协议的模式。

库 ID 使用小写字母、数字、_ 和 -，必须以字母开头，助手会将其作为传递给工具的值。最多可配置十个库。重复使用 --vault 可公开多个库：

obsidian-mcp serve \
  --vault work=/Users/me/Documents/WorkVault \
  --vault personal=/Users/me/Documents/PersonalVault

允许使用网络、可移动、隐藏和同步位置，因为显式指定 --vault 即视为授权；所有位置均适用相同的路径包含性保护。

设计原则

• 在进程启动时明确列出允许访问的库。
• 所有工具路径均相对于库目录，经过路径段检查，并禁止访问符号链接和保留状态。
• 文件变更会写入日志、进行冲突检查、以原子方式替换，并作为一个事务回滚。
• 服务绝不会监听网络接口，也不会发送遥测数据。
• stdout 专用于 MCP 消息；结构化诊断信息会发送到 stderr。
• 结果大小受限，适当时支持分页，并同时提供文本和结构化内容。

工具

工具	用途
obsidian_list_vaults	列出已配置的 vault ID，不暴露主机路径。
obsidian_read_note	读取笔记的限定页面，并返回其 SHA-256 etag。
obsidian_create_note	以原子方式创建笔记，不覆盖现有内容。
obsidian_edit_note	追加、前置或替换笔记的精确内容。
obsidian_delete_note	将笔记移至 MCP 回收站，或在明确确认后永久删除。
obsidian_move_note	移动或重命名笔记，并以事务方式更新明确无歧义的反向链接。
obsidian_create_directory	以事务方式在 vault 中创建目录。
obsidian_search_vault	使用带游标的分页搜索内容、文件名或标签。
obsidian_add_tags	以原子方式为一个或多个笔记添加标签。
obsidian_remove_tags	以原子方式移除精确匹配、嵌套或通配符选中的标签。
obsidian_rename_tag	以原子方式重命名整个 vault 中的标签。
obsidian_manage_tags	使用相同实现的统一标签添加／移除工作流。

所有架构都是根据 Zod 生成的严格 JSON Schema 2020-12 契约。变更操作的结果包含事务 ID；工具失败时会返回 isError: true 以及可执行的错误代码。

读取与并发

obsidian_read_note 会返回 etag。在需要避免更新丢失时，将其作为 if_match 传给编辑、移动或删除操作。批量标签操作接受 expected_etags 映射。笔记已更改时会返回 REVISION_CONFLICT，而不会覆盖笔记。

较大的笔记会使用与路径和 etag 绑定的不透明游标进行分页。搜索使用与查询和选项绑定的不透明游标。工具文本响应上限为 25,000 个字符。

删除与恢复

默认使用回收站。已删除笔记的字节内容和元数据会分别存储在 .obsidian-mcp/trash 下；元数据绝不会注入笔记。永久删除要求 confirm_path 与规范相对路径完全匹配。

事务和恢复快照存储在 .obsidian-mcp/transactions 中。已完成的数据会保留 30 天；默认情况下，超过 1 GiB 时会从最旧的数据开始清理：

obsidian-mcp serve --vault work=/path \
  --recovery-days 14 \
  --recovery-max-bytes 536870912

MCP 服务停止时，可检查或恢复已完成的事务：

obsidian-mcp recovery list --vault work=/path
obsidian-mcp recovery restore --vault work=/path --id <transaction-id>

如果所选事务之后内容已发生更改，恢复操作会拒绝覆盖。永久删除的快照会在提交后清除，无法恢复。

路径和文件系统安全

服务端会：

• 规范化已配置的 vault 根目录，并拒绝重复或嵌套的根目录；
• 拒绝绝对路径、UNC 路径、Windows 驱动器路径、NUL、反斜杠、空路径和点段工具路径；
• 禁止工具访问 .obsidian、.obsidian-mcp、.git、.backup 和 .trash；
• 检查现有目标，以及新目标最近的现有祖先；
• 拒绝符号链接、联接和重解析点路径，并在扫描时跳过这些路径；
• 不通过执行 shell 来验证文件系统；
• 严格解码 UTF-8，不会静默替换无效字节。

进程需要对每个已配置的 vault 具有读写权限。obsidian-mcp doctor --vault id=/path 会验证启动就绪状态和恢复状态。

链接和标签行为

移动操作可识别 Obsidian Wikilinks、嵌入内容、Markdown 链接、别名、URL 编码的目标、标题和块锚点。只有在链接明确指向源笔记时才会重写；有歧义的链接会被报告并保持不变。除非请求 backlink_action: "mark_broken"，否则删除操作会保留反向链接。

标签遵循 Obsidian 不区分大小写的规则，并支持 Unicode、表情符号、_、-、/ 和嵌套标签。Frontmatter 标签以 YAML 列表形式写入。行内标签处理会忽略围栏代码、行内代码和 HTML 注释。通配符使用有界匹配器，而非正则表达式。

开发

npm ci
npm run typecheck
npm test
npm run build
npm run ci

每个工具都在 src/tools/<tool>/index.ts 下有一个类型化定义；src/tools/index.ts 中的小型注册表负责应用共享的 MCP 注册和响应行为。文件系统、事务、Markdown、链接和搜索行为位于可复用的实用工具中。新增工具必须对每条路径使用 VaultFs，使用 TransactionManager 执行修改，并采用严格的输入／输出架构、结构化结果、注释以及安全／集成测试。

有关 1.x 迁移，请参阅 MIGRATING.md；有关漏洞报告，请参阅 SECURITY.md。

启动错误和兼容性警告只会写入 stderr，并包含稳定的代码、检测到的问题、确切的修复方法、验证步骤，以及指向对应迁移章节的链接。如果看不到服务，请在 MCP 客户端日志中查找代码，并使用诊断参考。

许可证

MIT