obsidian-local-rest-api MCP工具

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
• Browser clients and response headers
• Patching notes
• Raw-content mode
• Targeting specific sections
• Searching
• MCP (Model Context Protocol)
• Protocol revisions
• Connecting a client
• Available tools
• Binary files and attachments
• Available resources
• API Extensions
• Typed extension API
• 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.

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

API Extensions

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

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.

Known extensions

• Periodic Notes: Adds support for periodic notes