obsidian-local-rest-api MCP工具

The configuration directory is off-limits

The API refuses to read or write any file inside Obsidian's configuration directory (app.vault.configDir, normally .obsidian) — for both REST and MCP, reads as well as writes. A request for such a path is rejected with 403 (error code 40321) at the REST layer or a path error from an MCP tool.

That directory holds plugin code and each plugin's data.json — including this plugin's own, where your API key is stored. Writing into it is effectively remote code execution, since Obsidian runs an enabled plugin's main.js; reading from it leaks those secrets. Blocking it keeps a credential documented as "vault file access" from silently granting more (see GHSA-66m9-r757-qvq7).

The check is against where a path lands on disk, not just how it is spelled: a Windows 8.3 short name such as OBSIDI~1, a differently cased spelling on a case-insensitive filesystem, or a symlink that points into the configuration directory is refused the same way. Search and the tag listing skip any indexed note that lives there too, so a symlinked folder cannot hand the contents out by another route.

If you deliberately manage your Obsidian configuration through the API, turn on Settings → Local REST API → Advanced settings → Allow access to the configuration directory. It is off by default, and turning it on grants every holder of your API key that access.

Local REST API with MCP

Give your scripts, browser extensions, and AI agents a direct line into your Obsidian vault via a secure, authenticated REST API.

• Interactive API docs: https://coddingtonbear.github.io/obsidian-local-rest-api/
• Obsidian Community page: https://community.obsidian.md/plugins/obsidian-local-rest-api/

• What you can do
• Quick start
• REST API
• MCP clients
• Claude Code
• Claude Desktop
• Cursor
• Other clients
• API overview
• The configuration directory is off-limits
• Failed authentication is throttled
• Browser clients and response headers
• Patching notes
• Raw-content mode
• Targeting specific sections
• Searching
• Event streams
• Server state
• MCP (Model Context Protocol)
• Protocol revisions
• Connecting a client
• Available tools
• Binary files and attachments
• Signed URLs
• Available resources
• API Extensions
• Typed extension API
• Registering again after the host reloads
• MCP tools, resources, and prompts
• Documenting your routes
• Sub-resources under a note
• Extension events
• Extension state
• Known extensions
• Contributing
• Credits

REST API

```sh

API overview

For full request/response details, see the interactive docs.

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 ```

A text/* body is the content carrier, an application/json body the value carrier, and no body at all carries nothing (a delete, or a move via a Destination header). Target-Scope, Within (the instruction's within index as a plain integer, e.g. -1), Create-Target-If-Missing, Reject-If-Content-Preexists, and If-Match headers round out the instruction. See the interactive docs for the header encodings and the full details.

Already using the older header-driven PATCH format? It spread the instruction across request headers instead of a JSON body, and is deprecated and will be removed in 6.0. It still works — send Markdown-Patch-Version: 1 to opt back into it (the same header also selects the legacy ::-joined document map on GET), and responses served by it carry a Deprecation: true; sunset-version="6.0" header. To upgrade, drop that header and move each header into the JSON body; the interactive docs have the field-by-field mapping table. If your content contains headings, adjust their levels too: 1.x wrote them literally, and 2.x treats them as relative to the target (see the migration guide there).

See the interactive docs for the full instruction schema and options.

2. Follow the stream; with signed URLs on, the URL needs no API key

curl -N "<url>" ```

It takes two steps because a browser's EventSource can only make GET requests, which have no body to carry a filter.

The events are Obsidian's own, and only these can be streamed:

Each event is serialized by code written for it. That code decides exactly what is sent: the path, the file's NoteJson (the same shape /search/ evaluates), and a few event-specific fields such as oldPath on a rename. Note content is sent only when the filter reads file.content. Events whose payloads are keystrokes, clipboard data, or UI objects (editor-change, quick-preview, editor-paste, the menu events, …) can't be streamed. To react to frontmatter changes, use metadataCache changed: vault modify fires before Obsidian has re-read the file's metadata.

Each message's id is <epoch>-<counter>. A new epoch, or a gap in the counter, means events were missed. Nothing is replayed. A stream URL expires after the signed-URL lifetime (or ?ttl=<seconds>), but a stream opened before then stays open. At most 16 streams can be open at once. Anyone holding a signed stream URL sees the paths and metadata of every event its filter matches, so treat it like the notes themselves. See the API docs for the full message format.

API Extensions

Other plugins can register their own authenticated routes, public routes, MCP tools, streamable events, and state against this plugin's server. See Adding your own API Routes via an Extension for a walkthrough.

Public routes (addPublicRoute) are answered before the API key is checked, so they can't sit under a prefix the plugin serves its own routes from: /vault/, /active/, /search/, /commands/, /events/, /mcp/, /open/, and /tags/, in any letter case, along with /, the OpenAPI documents, and the certificate. A path whose first segment is a pattern (/:name/, /*) is refused for the same reason. addPublicRoute throws when you register one of these, so start public routes with a literal segment of your own, such as your plugin's id. Authenticated routes (addRoute) and vault sub-resources are unaffected.

Typed extension API

Install this package as a development dependency to get getAPI and the types for everything it returns:

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

This package declares obsidian, zod, and @types/express as peer dependencies, because its types refer to all three — addRoute returns express's IRoute, and addMcpTool takes zod schemas. npm installs peers for you; if you pin them yourself, keep them resolvable. Without them, TypeScript quietly widens those positions to any instead of reporting an error, so a project that suppresses the missing-types diagnostic gets no warning that it has lost type checking exactly where it matters most.

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

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

The package entry point is a small standalone module — it resolves the running host plugin out of Obsidian's plugin registry rather than pulling the plugin bundle into your build. Passing an extension API version (2 above) makes getAPI throw ApiVersionUnsupportedError when the installed host is older than the surface you need; omit it to accept whatever is installed and feature-detect yourself. getAPI returns undefined when the plugin isn't installed or hasn't loaded yet.

publicApi.d.ts is generated from src/publicApi.ts, which the implementation is compile-time-checked against, so the published types cannot drift from what the plugin actually offers.

Extension events

From extension API version 3, an extension can add its own events to the event streams. Each one is streamed under the extension's plugin id as the emitter:

const api = getAPI(this.app, this.manifest, 3);

// Your plugin's own Events instance; call this.events.trigger("task-completed", ...)
// wherever the event happens.
this.events = new Events();

api.addStreamableEvent("task-completed", {
  source: this.events,
  serialize: (file, line) => ({ path: (file as TFile).path, line }),
});
// Now available at POST /events/<your plugin id>/task-completed/

Your serializer decides everything a stream sends. The host adds emitter and event and sends nothing else, so return only what someone holding a stream URL should see. Return null to skip an occurrence. unregister() closes any open streams for your events.

Extension state

From extension API version 4, an extension can publish its own namespace in the state section of GET /, under its plugin id, for anything a client would read to decide whether to proceed: whether an index is built, when a sync last ran, how much work is queued.

const api = getAPI(this.app, this.manifest, 4);

api.addState({
  description: "Whether the semantic index is ready to query, and how far along a rebuild is.",
  schema: {
    type: "object",
    required: ["ready", "pending"],
    properties: {
      ready: { type: "boolean" },
      pending: { type: "integer", description: "Notes not yet indexed." },
      lastRunAt: { type: ["string", "null"], format: "date-time" },
    },
  },
  read: async () => ({ ready: this.index.ready, pending: this.queue.length, lastRunAt: this.lastRunAt }),
});
// Now served as state["<your plugin id>"] on every authenticated GET /

read is called on every authenticated GET /, concurrently with every other extension's, and raced against the read budget from the plugin's advanced settings. A read that overruns, rejects, or resolves to anything but a JSON object is served as null for your extension and logged to the console, once, until a read succeeds again; nothing else in the response is affected. Keep it cheap: compute in the background and hand back the latest result. The schema, if you give one, is merged into the GET / response schema at /openapi.yaml, so clients can rely on the shape; without it the namespace is documented as a free-form object. Either way the published entry also admits null, since that is what a failed read is served as. unregister() removes both.

Known extensions

• Periodic Notes: Adds support for periodic notes