obsidian-mcp-server

[!NOTE] 此仓库是 huaqing0 custom edition，基于 cyanheads/obsidian-mcp-server v3.5.0 遵循 Apache-2.0 许可证。它保留了上游服务器，并添加了本版本使用的本地工作区、 库结构和原生 Excalidraw 自动化。下方的 npm 和 MCPB 安装 链接仍指向上游发行版；此自定义版本目前仅以源代码形式提供。

工具

三十一个工具涵盖笔记内容、元数据、反向链接、原生 Excalidraw 自动化以及完整的库结构管理，并为 Obsidian 命令面板命令提供了一个受保护的逃生通道。

obsidian_get_note

以四种投影之一读取笔记，可通过保险库路径、活动文件或周期笔记（daily、weekly、monthly、quarterly、yearly）寻址。

• format: "content" — 原始 Markdown 正文

• format: "full" — 内容、frontmatter、标签和文件元数据；传入 includeLinks: true 以包含书面出站引用以及 Obsidian 解析后的出站链接和反向链接（仅限保险库内部 — 外部 URL 会被过滤）

• format: "document-map" — 标题、块引用和 frontmatter 字段的目录

• format: "section" — 单个标题/块/frontmatter 章节值（需要 section）；标题章节包含该标题下的完整子树

将文档映射投影与 obsidian_patch_note 配对使用，可在修补前发现编辑目标。

obsidian_search_notes

最多三种搜索模式，由 mode 选择：

• text — 带周围上下文窗口的子串匹配。contextLength 控制每个匹配两侧的上下文字符数（默认 100；如需更多上下文可调大）。可选 pathPrefix 过滤器（仅限文本模式 — 在其他任何模式中传入 pathPrefix 会被以 path_prefix_invalid_mode 拒绝）。

• jsonlogic — 针对 path、content、frontmatter.<key>、tags 和 stat.{ctime,mtime,size} 求值的 JSONLogic 树；自定义 glob 和 regexp 运算符，两者都接受 [PATTERN, VALUE] — 先模式后字段引用：{"glob": ["Projects/*.md", {"var": "path"}]}。相反的顺序会将笔记自身的字段编译为模式：glob 随后匹配不到任何内容，而 regexp 会直接对字段解析出的任何内容失败。这也是表达反向链接的方式，因为没有专门的工具或上游端点：{"regexp": ["\\[\\[Target Note(\\||#|\\]\\])", {"var": "content"}]} 返回每个正文中 wiki 链接到 Target Note 的笔记。

• omnisearch — 通过社区 Omnisearch 插件进行 BM25 排序搜索。支持带引号的短语、-exclusion、path: / ext: 过滤器、拼写容错、PDF + OCR 覆盖（通过 Text Extractor），以及在启用 AI Image Analyzer 索引时的视觉概念图像匹配。仅当插件的 HTTP 服务器在启动时可访问时，该模式才出现在模式枚举中；上游将结果硬性上限设为 50 — 缩小查询范围以显示更多结果（当可能达到上限时，响应会携带 truncated: true）。

结果根据 MCP 2025-11-25 规范 通过不透明游标进行分页：第一页省略 cursor，然后传递先前响应中的 nextCursor。每个结果都带有 totalCount（路径策略之后、分页之前）；最后一页省略 nextCursor。文本模式命中还会按文件在 maxMatchesPerHit（默认 10）处进行裁剪，以免单个命中密集的笔记撑爆响应预算——被裁剪的命中带有 truncated: true 和 totalMatches。

obsidian_write_note

创建或精准替换，并带有防止意外整文件覆盖的保护性默认值。

• 不带 section — 整文件 PUT。除非设置了 overwrite: true，否则拒绝覆盖现有文件。file_exists（Conflict）错误会建议使用 obsidian_patch_note / obsidian_append_to_note / obsidian_replace_in_note 进行就地编辑。

• 带 section — 针对指定标题/块/frontmatter 字段进行 PATCH-with-replace，其余文件内容保持不变。在 section 模式下会忽略 overwrite 标志。

当调用创建了新文件时，输出报告 created: true；当替换了现有文件或针对某个 section 时，报告 false。每个修改工具还会返回 previousSizeInBytes 和 currentSizeInBytes，以便代理发现意外的覆盖、上游意外行为或落在错误文件上的拼写错误路径。

obsidian_append_to_note

一个组合了 upsert 和 section 追加的原语，镜像了上游 Local REST API 的行为：

• 不带 section — POST 到 /vault/{path}。当文件存在时追加，当文件不存在时，用你的内容作为整个正文创建文件。 输出的 created: true 标记第二个分支，以便代理注意到拼写错误的路径或尚未创建的每日笔记是否悄然变成了一个全新文件。

• 带 section — 针对命名标题、块引用或 frontmatter 字段进行 PATCH-with-append。文件必须存在（否则 PATCH 预检会抛出 note_missing）。传入 createTargetIfMissing: true 可在现有文件内创建该 section 本身。块引用目标会与块行相邻拼接，不带分隔符——如果希望有分隔符，请在 content 中包含前导换行符。

在 upsert-create 分支上 previousSizeInBytes 为 0，否则为实际文件大小；currentSizeInBytes 是操作后从上游读取的写入后大小。将增量与 Buffer.byteLength(content) 进行比较，可检测自动换行注入或并发写入者。

obsidian_patch_note

在单个文档目标上进行精准编辑。

• operation: "append" 在 section 之后添加

• operation: "prepend" 在 section 之前添加

• operation: "replace" 替换该 section

• 目标：标题路径、块引用 ID 或 frontmatter 字段

标题目标接受完整的 Parent::Child 路径或裸叶子名称。如果裸叶子恰好匹配一个标题，则在写入前展开为完整路径，响应会回显编辑落到的定位符；如果叶子匹配多个标题，则会被拒绝并返回 ambiguous_section，其错误数据列出候选路径。相同的解析也适用于带 section 的 obsidian_write_note 和 obsidian_append_to_note。

在修补之前，使用 obsidian_get_note 并设置 format: "document-map" 来发现存在哪些目标。

obsidian_replace_in_note

用于不适合 obsidian_patch_note 结构化目标的编辑的搜索替换。会获取笔记，按顺序应用替换（每个替换都看到前一个的输出），然后通过一次 PUT 写回结果。

scope 选择替换运行的范围：

• body（默认）— YAML frontmatter 块之后的文本。该块会从原始字节重新附加，因此返回时字节完全相同。

• frontmatter — 仅 --- 分隔符之间的 YAML。分隔符本身永远不会被匹配。

• both — 每个替换先运行在 frontmatter 上，然后运行在 body 上；perReplacement[] 分别报告 bodyCount 和 frontmatterCount。

当 frontmatter 在范围内时，重写的 YAML 会在写入任何内容之前重新解析：如果它不再解析为属性映射，调用会以 frontmatter_invalid 失败，笔记保留其原始字节。该检查能捕获破坏的 YAML——标量中未加引号的 :、被重写为别名的列表标记、多余的引号。它无法捕获保持格式良好但含义不同的编辑，例如重命名键的子串冲突，或删除标量引号并改变其类型的替换。对于单个属性的类型化编辑，优先使用 obsidian_manage_frontmatter。

每个替换的选项：

• useRegex — 将 search 视为 ECMAScript 正则表达式。当 useRegex: true 时，替换会识别 $1 / $& 捕获组引用。

• caseSensitive — 当为 false 时，不区分大小写匹配

• wholeWord — 将模式包裹在 \b…\b 中；在字面模式和正则模式下均有效

• flexibleWhitespace — 将 search 中的任何空白序列替换为 \s+。仅字面模式——当 useRegex: true 时无效（请直接表达）。

• replaceAll — 当为 false 时，仅替换第一个匹配项。在 scope: 'both' 下，该替换会优先匹配 frontmatter（如果匹配），否则匹配 body。

字面模式会原样保留替换中的 $1 / $&——只有 useRegex: true 才会展开捕获组引用。

obsidian_manage_tags

在笔记上添加、移除或列出标签。操作两种表示之一，默认使用规范的 Obsidian frontmatter 位置：

• location: 'frontmatter'（默认）— 仅 frontmatter 中的 tags: 数组；笔记正文保持不变

• location: 'inline' — 仅正文中的内联 #tag 语法；add 在文件末尾追加 #tag

• location: 'both' — 选择加入跨两种表示的协调

add 确保标签在请求的位置存在；remove 移除它；list 忽略输入的 tags 数组。围栏代码块中的内联 #tag 出现会被有意忽略。

内联模式仅读取和写入笔记正文——YAML 标量中的 # 属于 frontmatter，因此既不会被列为内联标签，也不会被移除操作重写。移除内联标签时，会恰好带走一个相邻的水平空格——标签前面的那个，或者当没有前导空格时，标签后面的那个；其他每个字节都会保留，包括嵌套列表缩进、四空格缩进的代码块、尾随两空格硬换行以及表格单元格填充。

obsidian_delete_note

永久删除笔记。默认关闭。 设置 OBSIDIAN_ENABLE_DELETE=true 以在 tools/list 中暴露它。第一次调用会返回确认请求而不是删除——提示中包含文件的字节大小，因此破坏范围在用户确认前可见——然后使用答案重试该工具。拒绝或取消会使调用以 cancelled 失败，并且不会发出 DELETE；destructiveHint 注解也会在宿主审批流程中显示该操作。输出报告 previousSizeInBytes（删除时的字节大小）和 currentSizeInBytes: 0。

确认不是可选的，也没有回退路径：无法提供输入往返的客户端无法完成删除。所有其他工具不受影响。

仓库结构工具

obsidian_create_folder 幂等地创建嵌套文件夹。obsidian_move_path 通过 Obsidian 的原生 FileManager 移动或重命名文件或文件夹，创建缺失的目标父目录，并允许 Obsidian 更新内部链接。obsidian_delete_folder 默认使用 Obsidian 配置的回收站行为递归删除文件夹，或在明确请求时永久删除；它与笔记删除一起由 OBSIDIAN_ENABLE_DELETE=true 门控。

obsidian_execute_command

按 ID 调度 Obsidian 命令面板命令（可通过 obsidian_list_commands 发现）。行为取决于命令——有些命令打开 UI，有些删除文件或关闭仓库。

默认关闭。 当 OBSIDIAN_ENABLE_COMMANDS 未设置时，obsidian_execute_command 及其发现伙伴 obsidian_list_commands 都会被 disabledTool() 包裹——从 tools/list 中缺席（LLM 无法调用它们），但在面向操作员的清单中仍然可见，并带有启用提示。

Related MCP server: Obsidian Tools MCP Server

路径策略（文件夹范围权限）

三个可选环境变量控制每个工具可以针对哪些仓库路径。默认未设置 = 完整仓库，读写均如此——向后兼容。

匹配是基于前缀的，隐式递归，不区分大小写，尾随斜杠会被规范化。projects/ 匹配 projects/a.md、projects/sub/b.md 等。

写入路径隐式可读——你无法合理地编辑你看不到的内容。因此，当目标匹配 READ_PATHS 或 WRITE_PATHS 时，读取通过。

OBSIDIAN_READ_ONLY=true 在路径检查之前短路——每个写入工具和命令面板对在启动时都会被 disabledTool() 包裹（从 tools/list 中缺席），任何仍然到达服务的写入都会在运行时被拒绝，无论 WRITE_PATHS 如何。

拒绝的类型为 path_forbidden（JSON-RPC 代码 Forbidden），并在 data.recovery.hint 和 data.activeScope 中回显活动范围，以便 LLM 无需检查服务器日志即可自我纠正。obsidian_search_notes 的搜索结果会静默地根据 READ_PATHS 过滤——显示“我们隐藏了 N 个命中”的指示器会破坏门控。

标签列表是仓库范围的。 obsidian_list_tags 和 obsidian://tags 资源会聚合整个仓库的标签名称，并且不会被 OBSIDIAN_READ_PATHS 收窄——它们没有可门控的路径，因此读取范围之外的标签名称（绝不包含笔记内容）可能会浮现。

启动横幅会记录活动范围，以便操作员在启动时验证其配置。

资源

所有资源数据也可以通过工具访问——obsidian_get_note 对应 obsidian://vault/{+path}，obsidian_list_tags 对应 obsidian://tags。资源的存在是为了那些更喜欢将特定笔记或仓库快照附加到对话中的客户端。标签对不是镜像：obsidian://tags 保持快照语义，并原样返回上游负载且不排序，而 obsidian_list_tags 按计数排序并设置上限。

基于 @cyanheads/mcp-ts-core 构建：

• 声明式工具与资源定义——每个原语一个文件，框架负责注册与校验

• 统一错误处理——处理器抛出异常，框架捕获、分类并格式化。工具通过类型化的 errors[] 契约声明其失败面。

• 在 initialize 上提供服务器级 instructions——将部署特定的使用说明（活动路径策略、只读模式、命令面板开关）连同静态工具/资源目录一起呈现给符合规范的客户端

• HTTP 传输层可插拔认证：none、jwt、oauth

• 结构化日志，可选 OpenTelemetry 追踪

• STDIO 与 Streamable HTTP 传输

服务器本身是无状态的——每次工具调用都直接访问 Local REST API。框架的存储后端、请求状态 KV 和进度流在此处均未使用；Obsidian 是单仓库（vault）的，调用之间无需持久化任何内容。

Obsidian 特定功能：

• 封装 Obsidian Local REST API 插件——类型化客户端，确定性错误映射

• 通过 PATCH-with-target 操作，在标题、块引用和 frontmatter 字段之间进行感知区块的编辑

• 标签协调覆盖两种表示形式：frontmatter tags: 数组与行内 #tag 语法（跳过围栏代码块）

• 最多支持三种模式的搜索：文本、JSONLogic，以及（当插件可访问时）BM25 排序的 Omnisearch——按 MCP 2025-11-25 规范进行游标分页，文本模式下按文件裁剪匹配片段

• 破坏性删除需要人工确认——在两种协议修订版上均提供多轮往返的 input_required 回合，工具中不存在未经确认的删除路径

• 原生 vault 结构管理：创建文件夹、移动/重命名文件或文件夹并更新 Obsidian 链接、通过回收站或永久删除方式删除文件夹

• 原生 Excalidraw Automation API 集成：语义化创建/读取/添加/更新/删除、确定性布局、完整性校验、PNG 预览导出以及幂等笔记嵌入

• 通过 OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS 实现文件夹级读写权限，以及全局 OBSIDIAN_READ_ONLY 总开关——拒绝时返回类型化的 path_forbidden，并在错误数据中回显当前作用域

• 可选加入的命令面板对（obsidian_list_commands + obsidian_execute_command）——仅在 OBSIDIAN_ENABLE_COMMANDS=true 时注册

• obsidian_get_note 和 obsidian_open_in_ui 上的宽容路径解析——对大小写不匹配的路径静默重试规范文件名，遇到歧义的大小写匹配时抛出 Conflict，并在仅存在近似匹配时用 Did you mean: …? 建议丰富 NotFound。obsidian_delete_note 被有意排除——破坏性操作不应静默重写目标路径。

快速开始

将以下内容添加到你的 MCP 客户端配置文件中。Obsidian Local REST API 插件必须已在你的 vault 中安装并启用——参见 先决条件。

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务器。一次性运行可使用内联环境变量；如需重复使用，请将值复制到 .env（参见 .env.example）并运行 bun run start:http。

MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
# Server listens at http://127.0.0.1:3010/mcp by default

先决条件

• Bun v1.3.0 或更高版本（或 Node.js v24+）。

• Obsidian Local REST API 插件，v4.0.0 至 v5.x，已在你的 vault 中安装并启用。在 设置 → 社区插件 → Local REST API 中生成 API 密钥，并将其复制到 OBSIDIAN_API_KEY。插件 v6.0 移除了此服务器所固定的 markdown-patch 1.x 线上格式（用于区块定向写入和文档映射）。

• 周期性笔记目标（target: { "type": "periodic" }）额外需要插件 v5.0.1 或更早版本——v5.0.2 移除了内置的 /periodic/ 路由。所有其他目标类型不受影响。

• 一个能够回答输入请求（elicitation）的 MCP 客户端。obsidian_delete_note 在删除前始终要求确认，因此不支持该功能的客户端可以读写笔记，但无法删除笔记。

• 可选：安装并启用 Obsidian Excalidraw 插件以使用十一个绘图工具。其他笔记和 vault 工具不需要它。

• 此服务器默认使用 http://127.0.0.1:27123 以简化配置。在插件设置中启用 "Non-encrypted (HTTP) Server" 以使用该地址。若要改用始终开启的 HTTPS 端口，请设置 OBSIDIAN_BASE_URL=https://127.0.0.1:27124；插件的自签名证书由 OBSIDIAN_VERIFY_SSL=false（默认值）处理。

安装

1. 克隆仓库：

   git clone https://github.com/cyanheads/obsidian-mcp-server.git

2. 进入目录：

   cd obsidian-mcp-server

3. 安装依赖：

   bun install

4. 配置环境：

   cp .env.example .env
   # edit .env and set OBSIDIAN_API_KEY

配置

有关可选覆盖项的完整列表，请参阅 .env.example。

运行服务器

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t obsidian-mcp-server .
docker run --rm -e OBSIDIAN_API_KEY=your-key -p 3010:3010 obsidian-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/obsidian-mcp-server。默认安装 OpenTelemetry 对等依赖项——使用 --build-arg OTEL_ENABLED=false 构建可将其省略。

镜像在容器内绑定到 0.0.0.0（Docker 端口映射所需）。对于任何可从本机之外访问的部署，请设置 MCP_AUTH_MODE=jwt（配合 MCP_AUTH_SECRET_KEY）或 oauth——否则监听器会代表每个调用者将你的 OBSIDIAN_API_KEY 转发到 vault。

项目结构

开发指南

参见 CLAUDE.md 获取开发指南和架构规则。简要版本：

• 处理器抛出异常，框架捕获——工具逻辑中不使用 try/catch

• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 进行租户级存储

• 通过 src/mcp-server/*/definitions/index.ts 中的桶文件注册新工具和资源

• 包装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不虚构缺失字段

贡献

错误、功能请求和文档缺口应提交为 issue——参见 CONTRIBUTING.md 了解如何使其可操作，以及 CODE_OF_CONDUCT.md 了解我们的协作方式。安全报告通过 SECURITY.md 提交，绝不通过公开 issue。

欢迎提交小而自包含的修复的拉取请求。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情见 LICENSE。