obsidian-mcp-server

What it does

obsidian-mcp-server talks to a running Obsidian vault through the community Local REST API plugin. The server never opens vault files on disk. Each read and write goes as an HTTP call to the plugin inside the Obsidian app, so Obsidian has to stay open while you use this.

On the read side you get a note whole, as a structured record, as a map of its headings, or one section at a time. Folder and tag listings come with filters. Search takes plain text or a JSONLogic query over path, content, frontmatter and tags, and a ranked omnisearch mode shows up when the Omnisearch plugin answers at startup. Edits can be aimed at a single heading, block reference or frontmatter field instead of the whole file. There are also tools for regex replacements, frontmatter keys, tags and deletes. Every write reports the note's size before and after the change, which makes an accidental clobber easy to spot. Three resources sit next to the tools: a note by path, the full tag list, and the plugin's status.

Of the 14 tools, 12 are active by default. The two command-palette tools stay off until OBSIDIAN_ENABLE_COMMANDS is true. With OBSIDIAN_READ_ONLY set, the seven write tools and the command pair drop out and five remain. One of those five is obsidian_open_in_ui, because the code registers it with the read tools (src/index.ts and tools/definitions/index.ts). Folder allowlists and a deny list narrow what the tools can reach. The config code lowercases each entry and refuses to start when one is an absolute path, contains '..' or names the vault root (src/config/server-config.ts). Transport is stdio by default, with a local Streamable HTTP mode as the other choice.

What it needs

Copy the API key from Settings, Community Plugins, Local REST API in Obsidian and set it as OBSIDIAN_API_KEY. The default address http://127.0.0.1:27123 needs the plugin's 'Non-encrypted (HTTP) Server' switched on. Otherwise set OBSIDIAN_BASE_URL to https://127.0.0.1:27124. From Docker, point OBSIDIAN_BASE_URL at http://host.docker.internal:27123. Periodic-note targets on plugin v5.0.2 and later need the periodic-notes API extension. The omnisearch mode needs the Omnisearch plugin's HTTP server.

Limits

• Limit Works only while Obsidian is open with the plugin reachable; calls fail with obsidian_unreachable otherwise
• Not covered No backlinks tool; a JSONLogic regex search over content stands in
• Size cap obsidian_list_notes stops at 1,000 entries and walks 2 levels by default, up to 20 with depth
• Size cap obsidian_list_tags returns 200 tags by default, up to 10000 with limit
• Size cap Omnisearch keeps its top 50 hits before quoted phrases and exclusions are applied
• Limit Omnisearch is probed once at startup, so the server must restart to pick it up
• Not covered With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, JSONLogic searches lose the links and backlinks fields
• Limit On plugin v4.x, heading writes to notes with CRLF line endings land mid-line
• Limit Plugin v6.0 breaks two table-row write forms; target the table by an ID on its last row instead
• Limit Deletes have no undo beyond Obsidian's local trash

Works only while Obsidian is open with the plugin reachable; calls fail with obsidian_unreachable otherwise. There is no backlinks tool (a JSONLogic regex search stands in). obsidian_list_notes stops at 1,000 entries and goes 2 levels deep by default (up to 20); obsidian_list_tags returns 200 tags by default, up to 10000; omnisearch results are capped at 50 by the plugin. Omnisearch is probed once at startup, so the server must restart to pick it up. On plugin v4.x, heading writes to notes with CRLF line endings land mid-line; plugin v6.0 breaks two table-row write forms. Deletes have no undo beyond Obsidian's trash.

Who it suits

Suits someone who keeps notes in Obsidian on their own machine and wants an assistant to make targeted edits (one heading, one frontmatter key, a tag) rather than rewrite whole files, and who is willing to install the Local REST API plugin. The read and write allowlists, the deny list and the read-only switch make it workable for letting an assistant into part of a vault while keeping a private folder out. It is a community project, not from Obsidian. It is not a fit for a vault on a machine where Obsidian is not running, such as a server or a synced folder read without the app.