obsidian-mcp-server (cyanheads)
Surgical Obsidian vault editing — read, write, search, and patch notes, tags, and frontmatter.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y obsidian-mcp-server@latestPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"obsidian-mcp-server-cyanheads": {
"command": "npx",
"args": [
"-y",
"obsidian-mcp-server@latest"
],
"env": {
"OBSIDIAN_API_KEY": "<your-obsidian-rest-api-key>",
"OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
"OBSIDIAN_VERIFY_SSL": "false"
}
}
}
}Before you start
- Bun v1.3.11+ or Node.js v24+ (run via bunx/npx, no global install needed)
- Obsidian desktop app with the Local REST API community plugin v4.0.0+ installed and enabled
- An API key generated in the Local REST API plugin settings, supplied as OBSIDIAN_API_KEY
- The plugin's base URL (defaults to http://127.0.0.1:27123); Obsidian must be running for the server to work
- Optional: the Omnisearch plugin for BM25-ranked semantic search
About obsidian-mcp-server (cyanheads)
obsidian-mcp-server (by cyanheads) is a stdio/HTTP MCP server that gives AI agents structured, surgical access to an Obsidian vault. It connects to Obsidian through the Local REST API community plugin, so all reads and writes go through your running Obsidian instance rather than touching files on disk directly.
Beyond plain read/write, it specializes in section-aware editing: you can target specific headings, block references, or frontmatter fields and patch them in place instead of rewriting whole notes. Search is multi-mode — plain text, structured JSONLogic queries, and BM25-ranked Omnisearch when that plugin is installed.
It is built for safety in agentic workflows: folder-scoped read/write permissions, a global read-only kill switch, human-in-the-loop confirmation for destructive deletes, and case-forgiving path resolution that offers "did you mean?" suggestions when a note path is slightly off.
Tools & capabilities (14)
obsidian_get_noteRead a note's content and metadata by path
obsidian_list_notesList notes, optionally scoped to a folder
obsidian_list_tagsEnumerate all tags used across the vault
obsidian_search_notesMulti-mode search: text, JSONLogic, or BM25 Omnisearch
obsidian_write_noteCreate or overwrite a note at a given path
obsidian_append_to_noteAppend content to the end of an existing note
obsidian_patch_noteSurgically edit a note targeting a heading or block reference
obsidian_replace_in_noteFind-and-replace text within a note
obsidian_manage_frontmatterRead and update YAML frontmatter fields
obsidian_manage_tagsAdd or remove tags on a note
obsidian_delete_noteDelete a note (with human-in-the-loop confirmation)
obsidian_open_in_uiOpen a note in the Obsidian UI
obsidian_list_commandsList available Obsidian command-palette commands
obsidian_execute_commandRun an Obsidian command (opt-in via OBSIDIAN_ENABLE_COMMANDS)
When to use it
- Use it when you want an agent to update a specific section of a note (a heading or block) without rewriting the whole file
- Use it when you need to maintain frontmatter metadata or tags programmatically across many notes
- Use it when you want AI-assisted search over a large vault using text, structured JSONLogic, or BM25 ranking
- Use it when you need folder-scoped permissions or read-only mode so an agent can't touch sensitive areas of the vault
- Use it when you want to append daily-log entries or capture notes into Obsidian from an assistant
Quick setup
- 1In Obsidian, install and enable the Local REST API community plugin and copy its API key
- 2Add the server to your MCP client config with command `bunx`/`npx` and args `obsidian-mcp-server`
- 3Set the OBSIDIAN_API_KEY env var (and OBSIDIAN_BASE_URL if not the default 127.0.0.1:27123)
- 4Optionally set OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS and OBSIDIAN_READ_ONLY to scope access
- 5Restart your MCP client (Claude Desktop, etc.) and confirm the obsidian_* tools appear
- 6Verify by calling obsidian_list_notes or obsidian_get_note on a known note
Security notes
Needs the Obsidian Local REST API plugin's bearer token (OBSIDIAN_API_KEY) with full vault access; keep it in env vars. SSL verification is off by default (OBSIDIAN_VERIFY_SSL=false) because the plugin uses a self-signed cert, so only connect to a trusted local host.
obsidian-mcp-server (cyanheads) FAQ
Why does it need the Local REST API plugin instead of reading files directly?
The server talks to Obsidian over HTTP through that plugin, which keeps the vault index and plugins in sync and lets it use features like the command palette and Omnisearch. Obsidian must be running.
How do I authenticate?
Generate an API key in the Local REST API plugin settings and pass it as the OBSIDIAN_API_KEY environment variable. The MCP server itself can optionally add JWT/OAuth, but by default no extra auth is required for stdio.
Can I stop an agent from deleting or overwriting notes?
Yes. Set OBSIDIAN_READ_ONLY for a global write kill switch, scope writes with OBSIDIAN_WRITE_PATHS, and deletes require human-in-the-loop confirmation.
Does it support running Obsidian commands?
Yes, via obsidian_list_commands and obsidian_execute_command, but command execution is opt-in and gated behind the OBSIDIAN_ENABLE_COMMANDS environment variable.
Will it work with both stdio and HTTP clients?
Yes. It supports STDIO (the default for desktop clients) and Streamable HTTP transport for remote/hosted setups.
Alternatives to obsidian-mcp-server (cyanheads)
Self-hosted MCP server for Jira and Confluence Cloud and Server/Data Center.
Official Notion server to read, search, create, and update pages and databases in your workspace.
Read, search, and edit your Obsidian vault through the Local REST API community plugin.
Compare obsidian-mcp-server (cyanheads) with: