带 MCP 的本地 REST API

为你的脚本、浏览器扩展和 AI 代理提供一条直达 Obsidian 仓库的安全、经过认证的 REST API 通道。

• 交互式 API 文档： https://coddingtonbear.github.io/obsidian-local-rest-api/

• Obsidian 社区页面： https://community.obsidian.md/plugins/obsidian-local-rest-api/

• 你能做什么

• 快速开始

  • REST API

  • MCP 客户端

    • Claude Code

    • Claude Desktop

    • Cursor

    • 其他客户端

• API 概览

• 补丁说明

  • 原始内容模式

• 定位特定章节

• 搜索

• MCP（模型上下文协议）

  • 协议修订

  • 连接客户端

  • 可用工具

  • 可用资源

• API 扩展

  • 类型化扩展 API

  • 已知扩展

• 参与贡献

• 致谢

你能做什么

通过 REST API 或 内置的 MCP 服务器 访问你的仓库——两个接口暴露相同的核心能力，因此脚本、浏览器扩展和 AI 代理都使用同一种语言。

• 读取、创建、更新或删除笔记——对仓库中的任何文件（包括二进制文件）执行完整的 CRUD 操作

• 精准修补特定章节——定位标题、块引用或 frontmatter 键，仅对该章节执行追加、前置、替换、删除或移动操作，而不触碰文件的其他部分

• 搜索你的仓库——简单的全文搜索，或针对笔记元数据（frontmatter、标签、路径、内容）的结构化 JsonLogic 查询

• 访问当前活动文件——读取或写入 Obsidian 中当前打开的任意笔记

• 列出并执行命令——触发任何 Obsidian 命令，就像你使用了命令面板一样

• 查询标签——列出整个仓库中的所有标签及其使用次数

• 在 Obsidian 中打开文件——让 Obsidian 在其界面中打开指定笔记

• 扩展 API——其他插件可以通过 API 扩展接口 注册自己的路由

所有请求均通过自签名证书以 HTTPS 提供服务，并以 API 密钥认证作为访问门槛。

Related MCP server: Connect MCP

快速开始

安装并启用插件后，打开 设置 → Local REST API 即可找到你的 API 密钥和证书。

REST API

# Check the server is running (no auth required)
curl -k https://127.0.0.1:27124/

# List files at the root of your vault
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/

# Read a note
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md

# Read a specific heading (URL-embedded target)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append a line to a specific heading (PATCH with a JSON instruction)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["My Section"],"operation":"append","content":"New line of content"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

为避免证书警告，你可以从 https://127.0.0.1:27124/obsidian-local-rest-api.crt 下载并信任该证书，或让 HTTP 客户端直接指向它。

MCP 客户端

MCP 服务器运行在 https://127.0.0.1:27124/mcp/，需要通过 Authorization 请求头提供你的 bearer 令牌进行认证（即 Authorization: Bearer <your-api-key>）。由于插件使用自签名证书，你可能需要在操作系统/客户端中信任该证书，或使用位于 http://127.0.0.1:27123/mcp/ 的纯 HTTP 端点（在 设置 → Local REST API → 启用 HTTP 服务器 下开启）。

Claude Code

Claude Code 原生支持 HTTP MCP。最快的方式是通过 CLI 添加服务器：

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your-api-key>"

或者手动将其添加到项目根目录的 .mcp.json 中（项目级作用域），或通过 claude mcp add --scope user 进行用户级全局配置：

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Claude Desktop

Claude Desktop 不原生支持远程 HTTP MCP 服务器，但你可以通过 mcp-remote 进行桥接（需要 Node.js）。将以下内容添加到 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://127.0.0.1:27124/mcp/",
        "--header",
        "Authorization: Bearer <your-api-key>"
      ]
    }
  }
}

保存文件后重启 Claude Desktop。

Cursor

Cursor 支持 Streamable HTTP MCP 传输。将以下内容添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）：

{
  "mcpServers": {
    "obsidian": {
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

其他客户端

任何支持 Streamable HTTP 传输的 MCP 客户端都可以通过 Authorization: Bearer <your-api-key> 请求头连接到 https://127.0.0.1:27124/mcp/。请查阅你所用客户端的具体配置格式文档。

API 概览

完整的请求/响应详情请参阅交互式文档。

补丁说明

PATCH 方法是此 API 最有用的功能之一。它让你无需重写整个文件即可进行精准编辑。

发送一个 JSON 指令：一个操作（replace、prepend、append 或 delete）应用于某个目标的作用域（content、marker、markerAndContent 或 parent）——目标可以是标题（以从顶层向下的标题文本数组表示）、块引用或 frontmatter 键。负载通过 content（字符串）、value（JSON，用于 frontmatter 值）或 destination（标题移动）传递：

# Replace the value of a frontmatter field
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"frontmatter","target":"status","operation":"replace","value":"done"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

content 字符串中的标题层级相对于目标而言（开头的 # 表示直接子级）。警告性提示（例如标题被重新提升超过第 6 级）会以百分号编码的 JSON 形式出现在 Markdown-Patch-Warnings 响应头中——解析前请使用 decodeURIComponent 解码。传入 ifMatch（来自文档映射的 version）可实现乐观并发控制。

注意： 空白字符归库所有——你的内容会被缩减为修剪后的规范形式（开头和结尾的空行没有意义），API 本身会在插入内容面对正文文本时提供空行，因此 append 或 prepend 总是作为独立块落地，绝不会合并到现有段落中。标题行、现有空行以及每个文档的间距风格都会原样保留。有关实际示例，请参阅交互式文档。

要延续现有块而不是新建一个——例如扩展列表——请在标题指令中添加 within：一个索引，用于选择该章节的顶层正文块之一（从 0 开始按文档顺序计数，负数从末尾倒数，因此 -1 是最后一个块）。within 编辑按字面拼接，因此连接处由你掌控：

# Add an item to the last list under "Log" (the leading \n continues the block)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["Log"],"within":-1,"operation":"append","content":"\n- new item"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

使用 markerAndContent 作用域时，prepend/append 改为在被索引块旁边插入一个新块。索引是位置性的，因此请先读取文档映射，并将编辑与 ifMatch 配对使用。

原始内容模式

如果你的客户端将 markdown 模板化到请求体中（Shortcuts、Tasker、来自模板的 curl），将内容 JSON 转义到指令中会很脆弱。原始内容模式将指令的字段移出请求体——目标放在 URL 中（或放在 Target-Type/Target 请求头中，并显式指定 Markdown-Patch-Version: 2），操作和选项放在请求头中——而请求体就是原始负载，无需任何 JSON 转义：

# Append a templated line under a heading — no JSON escaping anywhere
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Operation: append" \
  -H "Content-Type: text/markdown" \
  --data "- $TEMPLATED_CONTENT" \
  https://127.0.0.1:27124/vault/notes/daily.md/heading/Log

text/* 请求体是 content 的载体，application/json 请求体是 value 的载体，没有请求体则不携带任何内容（用于 delete，或通过 Destination 请求头进行移动）。Target-Scope、Within（指令的 within 索引，以纯整数表示，例如 -1）、Create-Target-If-Missing、Reject-If-Content-Preexists 和 If-Match 请求头共同构成完整的指令。请求头编码和完整细节请参阅交互式文档。

已经在使用旧版基于请求头的 PATCH 格式？ 该格式将指令分散在请求头中而非 JSON 请求体中，现已弃用，将在 6.0 中移除。它仍然可用——发送 Markdown-Patch-Version: 1 即可选择使用旧格式（同一请求头也会在 GET 时选择旧版 :: 连接的文档映射），由该格式提供的响应会带有 Deprecation: true; sunset-version="6.0" 请求头。要升级，请去掉该请求头并将每个请求头字段移入 JSON 请求体；交互式文档中有逐字段的映射表。

完整的指令模式和选项请参阅交互式文档。

定位特定章节

你可以读取或写入笔记的特定部分——标题、块引用或 frontmatter 字段——而无需获取或替换整个文件。这适用于 GET、PUT、POST 和 PATCH 请求（对于 PATCH，这是原始内容模式——需添加 Operation 请求头）。

在文件名后追加 /<target-type>/<target>。 每个嵌套标题层级都是独立的路径段，因此文本中包含 :: 的标题无需转义：

# Read the content under a specific heading
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Read a nested heading (one path segment per level)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/Work/Meetings

# Read a frontmatter field
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/frontmatter/status

# Replace the content of a heading via PUT (heading levels are normalized for you)
curl -k -X PUT \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Updated content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append to a heading via POST
curl -k -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Appended content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

支持的目标类型：heading、block、frontmatter。

在 GET 请求中，Target-Scope 请求头选择返回目标的哪一部分，与 PATCH 的作用域对应：content（默认）、marker（标签——标题的原始文本、块的裸 id、frontmatter 键）或 markerAndContent（整个节点，其形态与 PATCH 在该作用域下 replace 所消费的完全一致——标题子树读回时其自身行显示为 # Title，层级相对于其父级）：

# Read a whole section — heading line included — ready to edit and write back
curl -k -H "Authorization: Bearer <your-api-key>" \
  -H "Target-Scope: markerAndContent" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

已弃用：基于请求头的定位。 早期版本使用 Target-Type、Target 和 Target-Delimiter 请求头（外加 Target-Scope/Trim-Target-Whitespace）来定位章节。该形式已弃用，将在 6.0 中移除；仅当你同时发送 Markdown-Patch-Version: 1 时才会被处理（响应随后会带有 Deprecation 请求头）。没有该请求头时，提供这些定位请求头会被以 400 拒绝。在单个请求中同时提供 URL 路径定位和请求头形式会返回 422 Unprocessable Entity。

搜索

POST /search/simple/?query=your+terms 运行 Obsidian 内置的模糊搜索，并返回带评分上下文片段的匹配文件名。

POST /search/ 接受一个 JsonLogic 表达式（内容类型为 application/vnd.olrapi.jsonlogic+json），并针对每条笔记的元数据（frontmatter、标签、路径、内容）进行评估。

MCP（模型上下文协议）

[!NOTE] 目前存在多个针对 Obsidian 的第三方 MCP 服务器，但它们已不再必要——本插件内置了一个 MCP 服务器，它运行在 Obsidian 内部，可直接访问你 vault 的实时元数据、当前活动文件和命令面板。如果你正在使用第三方服务器，切换到本服务器很可能会获得更好的效果。

本插件在 /mcp/ 路径下内置了一个 MCP 服务器，使 AI 代理和兼容 MCP 的客户端无需手工构造 HTTP 请求即可与你的 vault 交互。

传输方式： Streamable HTTP —— 需要 API 密钥认证。

协议版本

该端点提供 2026-07-28 版本以及从 2024-10-07 到 2025-11-25 的会话式版本，并按请求选择，因此两种客户端可以共用同一端点。

2026-07-28 版本是无状态的：没有 initialize 握手，也没有会话，因此插件既不会发出也不会读取 Mcp-Session-Id 头。每个请求都在 params._meta 中携带自己的协议版本和客户端身份，并在 MCP-Protocol-Version、Mcp-Method 和 Mcp-Name 头中重复这些信息，且各自独立应答。客户端可以调用 server/discover 预先了解支持的版本和功能。

以 initialize 请求开始的客户端将获得它们协商的会话式版本：握手返回一个 Mcp-Session-Id，GET /mcp/ 打开该会话的通知流，DELETE /mcp/ 结束该会话。会话仅存在于该路径上，也正是它们保证了握手中 listChanged 功能的真实性：当另一个插件注册或移除 MCP 工具时，每个活动会话都会收到通知，而 2026-07-28 客户端则通过 subscriptions/listen 流获知这一变化。

连接客户端

将你的 MCP 客户端连接到 https://127.0.0.1:27124/mcp/。认证使用 bearer token——在 设置 → Local REST API 下找到你的 API 密钥，然后按如下方式传递：

Authorization: Bearer <your-api-key>

具体配置语法因客户端而异；请参阅上方 快速开始 中的示例，或查阅你客户端关于 Streamable HTTP 远程 MCP 服务器的文档。

[!WARNING] 要安全地连接到 MCP 服务器，你的客户端必须信任本插件的自签名证书。你可以从 https://127.0.0.1:27124/obsidian-local-rest-api.crt 下载并信任它，或者将客户端配置为对 127.0.0.1 跳过 TLS 验证。

如果你的环境无法信任自签名证书，并且你已在 设置 → Local REST API → 启用 HTTP 服务器 中启用了 HTTP 端点，则可以使用 http://127.0.0.1:27123/mcp/ 而非 https://127.0.0.1:27124/mcp/ 进行不安全连接。

可用工具

可用资源

API 扩展

其他插件可以针对本插件的服务器注册自己的认证路由、公共路由和 MCP 工具。请参阅 通过扩展添加你自己的 API 路由 获取详细教程。

类型化扩展 API

安装此包作为开发依赖，即可获得 getAPI 及其返回内容的类型：

npm install --save-dev obsidian-local-rest-api

此包将 obsidian、zod 和 @types/express 声明为 peer 依赖，因为其类型引用了这三者——addRoute 返回 express 的 IRoute，而 addMcpTool 接受 zod schema。npm 会自动为你安装 peer 依赖；如果你自行固定版本，请确保它们可解析。如果没有这些依赖，TypeScript 会静默地将这些位置放宽为 any 而不是报告错误，因此一个抑制了缺失类型诊断的项目，在恰恰最需要类型检查的地方失去类型检查时，不会收到任何警告。

import { getAPI, type LocalRestApiPublicApi } from "obsidian-local-rest-api";

const api: LocalRestApiPublicApi | undefined = getAPI(this.app, this.manifest, 2);

包的入口是一个小型独立模块——它从 Obsidian 的插件注册表中解析出正在运行的主插件，而不是将插件包拉入你的构建。传入扩展 API 版本（上面的 2）会使 getAPI 在已安装的主插件版本旧于你所需的功能面时抛出 ApiVersionUnsupportedError；省略该参数则接受任何已安装的版本并自行进行特性检测。当插件未安装或尚未加载时，getAPI 返回 undefined。

publicApi.d.ts 由 src/publicApi.ts 生成，实现会针对后者进行编译时检查，因此发布的类型不会与插件实际提供的功能产生偏差。

已知扩展

• Periodic Notes：添加对周期性笔记的支持

参与贡献

请参阅 CONTRIBUTING.md。如果你想在不修改核心代码的情况下添加功能，可以考虑构建一个 API 扩展——扩展可以独立开发和发布。

致谢

灵感来自 Vinzent03 的 advanced-uri 插件，目标是突破自定义 URL scheme 的限制，扩展自动化选项。