coddingtonbear/obsidian-local-rest-api
A secure REST API and Model Context Protocol (MCP) server for your vault.
What it is
obsidian‑local‑rest‑api is an Obsidian plugin that runs a tiny HTTPS server inside the desktop app. The server exposes a REST API (and a built‑in Model Context Protocol – MCP server) that lets external programs – scripts, browser extensions, or AI agents – read, write, search, and manipulate notes in your vault.
Core capabilities
| Capability | How it works |
|---|---|
| File CRUD | GET/PUT/POST/PATCH/DELETE on /vault/{path} lets you fetch, create, replace, patch, or delete any markdown or binary file. |
| Targeted edits | PATCH (JSON body or header‑driven “raw‑content” mode) can modify a single heading, block reference, or front‑matter key – append, prepend, replace, delete, or move – without rewriting the whole file. |
| Active file | /active/ mirrors the note currently open in the Obsidian UI, so agents can read or update the file you’re working on. |
| Search | /search/simple/ runs Obsidian’s fuzzy search; /search/ accepts a JsonLogic expression to filter on metadata (tags, front‑matter, path, content). |
| Commands & UI | /commands/ lists all Obsidian commands; posting to /commands/{id}/ executes one. /open/{path} tells the UI to open a note. |
| Tag overview | /tags/ returns every tag in the vault with a usage count. |
| MCP server | The same functionality is also reachable via the Model Context Protocol (/mcp/), a streaming HTTP protocol used by AI tools like Claude Code, Claude Desktop (via mcp‑remote), and Cursor. |
| Extensibility | Other plugins can register extra routes or MCP tools through the provided extension API. |
How you talk to it
- The server runs on
https://127.0.0.1:27124/(HTTPS with a self‑signed cert) and optionally on plain HTTPhttp://127.0.0.1:27123/if you enable it. - Authentication is a Bearer token shown in Obsidian’s Settings → Local REST API.
- Example curl to list vault root:
curl -k -H "Authorization: Bearer <key>" https://127.0.0.1:27124/vault/
- For MCP‑compatible clients you point them at
https://127.0.0.1:27124/mcp/and supply the same bearer token.
Why it matters for AI
AI agents often need live access to a knowledge base. By exposing the vault over a standard HTTP API, the plugin lets LLM‑powered assistants (Claude, Cursor, custom bots, etc.) read context, update notes, run searches, and trigger Obsidian commands without manual copy‑pasting. The MCP layer adds a streaming, session‑aware protocol that matches the emerging Model Context Protocol spec, making the integration smoother for tools that already understand MCP.
Getting started
- Install the plugin from the Obsidian community plugins store.
- Enable it; note the generated API key and download the self‑signed certificate.
- Use the interactive Swagger‑like docs at https://coddingtonbear.github.io/obsidian-local-rest-api/ for request examples.
- Configure your AI client (Claude Code, Claude Desktop via
mcp‑remote, Cursor, etc.) with the endpoint and token as shown in the README.
Who might use it
- Developers building personal AI assistants that need to read/write their own notes.
- Automation scripts that want to keep a vault in sync with external data sources.
- Researchers experimenting with LLM‑driven note‑taking or knowledge‑graph construction.
TL;DR: A secure, authenticated HTTP interface (REST + MCP) for Obsidian that lets scripts and AI agents treat your vault like a remote file‑system, with fine‑grained patching, search, command execution, and extensibility.
Related
- Project
- Project
- Project
- Project
- Project