Local REST API for Obsidian MCP
Obsidian plugin with a REST API and a built-in MCP server: an agent reads, searches and surgically edits vault notes from Claude Code or Cursor
- 3,085 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The API key allows writing and deleting any vault file and running any Obsidian command
- Notes and attachments the agent reads through MCP enter the model context and go to its provider
- The server listens on 127.0.0.1 only, but any local program that knows the key can call it
Install
- Works in
Manual install
claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ --header "Authorization: Bearer <your-api-key>"Insert the key from the plugin settings. Obsidian must be running.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The API key allows writing and deleting any vault file and running any Obsidian command
- Notes and attachments the agent reads through MCP enter the model context and go to its provider
- The server listens on 127.0.0.1 only, but any local program that knows the key can call it
This is third-party code. Review the repository files before installing.
What it does
The plugin starts a local HTTPS server inside Obsidian at 127.0.0.1:27124 with a self-signed certificate. Access is gated by an API key shown in the plugin settings. The same capabilities are available through REST endpoints and through MCP at /mcp/ over Streamable HTTP. An agent lists files, reads notes together with frontmatter and tags, and creates, appends to, moves, copies and deletes files (deletion sends the file to the trash by default). The standout feature is surgical editing. The vault_patch tool changes one heading, block reference or frontmatter field without touching the rest of the note. Search is either plain full text or structured JsonLogic over note metadata. Beyond notes, the plugin can read the file currently open, list tags with usage counts, open a file in the Obsidian window and run any command from the command palette. For attachments there is vault_read_binary: images come back as a block the model can see, and other files come as a signed link. Other plugins can add their own routes through an extension interface.
Who it is for. For people who keep notes in Obsidian and want Claude Code, Cursor or a script to search the vault, append to a journal and edit individual sections.
Good fit when
- You need to append a line under a journal heading without rereading or overwriting the whole note: `vault_patch` with the append operation fits
- You want to find notes by properties such as tag and path, and structured `search_query` with JsonLogic covers it
- The agent should work with the note open in Obsidian right now: `active_file_get_path` returns its path
- The vault is on this same computer and Obsidian is running, so a local HTTP connection with no external services is enough
- Scripts and browser extensions need the same vault access through REST with an Authorization header
Not a fit when
- Obsidian is not running: the server lives inside the app, so with no open window there is nothing to connect to
- You need an MCP server that reads a Markdown folder directly without a plugin and works while Obsidian is closed
- The vault is on a phone or a server with no access to 127.0.0.1 on the machine where the agent and Obsidian run
- Nobody but you may read or change the notes, and you will not hand an agent an API key with write access
Example request
Find notes tagged project in my Obsidian vault and append a new line to the Tasks section of the note called Weekly planMCP
- Transport
- http
- Authentication
- API key
Limitations
- The plugin installs into Obsidian and works while the app is running. The API key is shown under Settings, Local REST API.
- The certificate is self-signed. Clients accept it once trusted, and curl is usually run with -k. The certificate authority can be downloaded from https://127.0.0.1:27124/obsidian-local-rest-api.crt.
- Claude Desktop does not support remote HTTP servers directly; it needs the mcp-remote bridge and Node.js.
- Signed URLs are on by default and can be switched off in the plugin's advanced settings.
- An MCP tool result of about a megabyte or more crashes Obsidian's renderer, so attachments are capped at 512 KiB.
- No paid accounts are required.
How to disable. Remove the server from the client with `claude mcp remove obsidian` or delete the obsidian block from `.mcp.json`. To close access entirely, disable the plugin under community plugins in Obsidian settings, and the server on port 27124 stops.
FAQ
How do I connect Obsidian to Claude Code through MCP?
Enable the Local REST API plugin, copy the key from its settings and run claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ --header "Authorization: Bearer <key>". The same block can go into the project's .mcp.json.
How do I set up Obsidian MCP for Claude Desktop?
Claude Desktop does not support remote HTTP servers directly, so claude_desktop_config.json uses the npx command with the mcp-remote@latest package, the address https://127.0.0.1:27124/mcp/ and an Authorization header. Restart Claude Desktop after editing. Node.js is required.
How do I change only one section of a note?
Use vault_patch or a PATCH request with a JSON instruction naming targetType (heading, block or frontmatter), target, operation and content. Operations are append, prepend, replace, delete and move. The rest of the file stays untouched.
How does the plugin differ from MCP servers such as mcp-obsidian?
The server is built into the plugin and uses the same key and port as the REST API, so no extra process or intermediary is needed. Servers like mcp-obsidian start with a separate command and connect to this plugin over REST.
What if the client complains about the certificate?
Download the plugin's certificate authority from https://127.0.0.1:27124/obsidian-local-rest-api.crt and trust it in your system or browser. An HTTP client can also be pointed at that file directly.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server for an Obsidian vault via the Local REST API plugin: search, read, append and patch notes
Obsidian MCP Server
obsidian-mcp-server
An MCP server for an Obsidian vault: read, search and precisely edit notes, sections, frontmatter and tags
A local MCP server for safe read, search and edit of notes in an Obsidian vault, restricted to the vault root
Obsidian MCP Plugin
obsidian-mcp-plugin
An Obsidian plugin: an MCP server runs inside Obsidian with eight tools for the vault, search and graph. Installed through the plugin catalog or .mcpb
Obsidian MCP
obsidian-mcp
A local MCP server for Obsidian vaults: reads and edits explicitly configured folders of Markdown files, Obsidian need not be open
Agent Client for Obsidian
Agent Client
An Obsidian plugin that runs Claude Code, Codex and other agents via the Agent Client Protocol right inside your notes vault
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Local REST API for Obsidian (this entry) | no | API key | 3,085 | |
| mcp-obsidian | no | API key | 4,507 | a separate MCP server that reaches the vault through this same plugin over REST and starts with its own command |
| Obsidian MCP Plugin | no | API key | 467 | also an Obsidian plugin with built-in MCP, offering eight tools for the vault, search and graph |
| Obsidian MCP Server | no | API key | 700 | an external MCP server for notes that starts as a separate process |
README in short
The page opens with a feature overview and a quick start: curl examples for REST and setup for the Claude Code, Claude Desktop and Cursor MCP clients. It then covers the endpoint overview, notes on targeted edits, section addressing, search types, event streams and server state. A large section is devoted to MCP: protocol revisions, the tool list, binary file handling, signed URLs and resources. The page ends with the extension interface for other plugins, the list of known extensions and contributor notes.