If you want to know how to connect Obsidian to AI agents without giving up control of your vault, the short answer is one plugin: Local REST API by Adam Coddington. It exposes your vault over a secure local REST API and a built-in Model Context Protocol (MCP) server, so Claude Code, Cursor, Claude Desktop, and any MCP-compatible client can read, write, search, and patch notes through structured tools. Your notes never leave your machine unless you already sync them somewhere else, and you can scope every action to a specific heading, block, or frontmatter field.
That sounds like a small thing. It isn’t. Once your vault is addressable, your second brain stops being a pile of Markdown and becomes a real knowledge base an agent can actually use. You can ask Claude Code to summarize a research thread from last month, have Cursor append a daily note with structured tags, or wire a script that catches every unfinished action item across the vault and dumps it into a single planning note. None of that requires uploading anything to a cloud service. The plugin is open source under MIT, has more than 671,000 downloads from Obsidian’s official community plugin directory, and ships its own MCP server at https://127.0.0.1:27124/mcp/.
This guide covers the full flow for how to connect Obsidian to AI agents: installing the plugin, exposing the MCP server, wiring Claude Code and Cursor to it, using the structured tools (vault_read, vault_write, vault_patch, search_query, command_execute, and friends), and the security and troubleshooting decisions that come up once the vault is actually addressable. By the end you’ll have a working setup you can extend into any workflow that benefits from an agent reading and writing your notes.
The reason to learn how to connect Obsidian to AI agents this way, instead of copy-pasting notes into a chat window, is control. The plugin runs on your machine, the agent connects to 127.0.0.1, and every request is gated behind an API key. You decide which client gets access, you decide which vault it can see, and you can revoke the key in one click when you’re done. That’s the same posture as self-hosted email or a local database, applied to your second brain.
What You Need Before You Start
You need three things, and only one of them is software.
An Obsidian vault you are okay with an automated client touching. It can be your real second brain, a fresh test vault, or a copy of a smaller folder you use for prototyping. The plugin reads, writes, and patches every file the vault has access to, which is the entire vault by default. Pick the vault deliberately. The single most common mistake people make when they first figure out how to connect Obsidian to AI agents is letting the agent loose on their primary vault before they’ve rehearsed the workflow on a disposable copy.
Obsidian 1.4 or later. The community plugin page lists the plugin’s minimum supported version, and it tracks current Obsidian releases. If your Obsidian is more than a year old, update it first.
An MCP-compatible client. Claude Code has native HTTP MCP support and is the easiest first target. Cursor works through its MCP client settings. Claude Desktop needs a small bridge package called mcp-remote because it doesn’t speak raw HTTP MCP. Any other MCP client that supports the Streamable HTTP transport will also work, including self-hosted agent frameworks. The choice of client determines the workflow language you use, but the MCP server stays the same on the Obsidian side.
If you have those three, you can have an agent addressing your vault in under fifteen minutes.
How to Connect Obsidian to AI Agents: Install the Local REST API Plugin
Open Obsidian, go to Settings → Community plugins, disable Restricted mode if it’s on, then click Browse and search for “Local REST API.” The official listing is “Local REST API with MCP” by Adam Coddington, and it appears at the top of the results. Click Install, then Enable.
Once the plugin is on, a new section called Local REST API appears under Settings → Community plugins → Local REST API. Open it. You’ll see your API key, a button to copy it, and toggles for the HTTPS server (default on, port 27124) and the HTTP server (default off, port 27123). Leave HTTPS on and HTTP off until you have a reason to do otherwise.
The plugin generates a self-signed certificate the first time it boots, so your browser and HTTP clients will warn you the certificate is untrusted. That’s expected. The certificate is local to your machine and the API key gates every request.
What the Plugin Actually Exposes
The plugin ships two interfaces that share the same underlying engine: a REST API and an MCP server. Both are documented in the project’s README on GitHub, and both let a script or agent do the same five things to your vault.
Read, create, update, or delete any file. Full CRUD, including binary files. That covers images, PDFs, and anything else you stash in the vault, not just Markdown notes.
Surgically patch a specific section. Instead of rewriting a whole note, you can target a heading, a block reference, or a frontmatter key and append, prepend, replace, or delete just that section. This is the operation that makes the plugin feel like a real knowledge-base interface rather than a file-sync hack. An agent can update a single line under “Open Questions” in a research note without disturbing the rest of the document.
Search the vault. There’s a simple full-text search endpoint and a structured search endpoint that takes JsonLogic queries against note metadata, including frontmatter, tags, path, and content. MCP clients call these through the search_simple and search_query tools.
Operate on the active file. The plugin exposes a parallel set of endpoints for whatever note is currently open in Obsidian. Useful when an agent wants to “edit the note I’m looking at” without the user naming a path.
Run Obsidian commands. The plugin can list every registered Obsidian command and execute any of them. That means an MCP client can trigger things like “open file,” “toggle a checkbox,” or “run Templater insert” through the command palette programmatically.
The MCP server exposes all of the above as structured tools. The full list, pulled from the project’s README, includes vault_list, vault_read, vault_write, vault_append, vault_patch, vault_delete, vault_move, vault_copy, vault_get_document_map, active_file_get_path, periodic_note_get_path, search_query, search_simple, tag_list, command_list, command_execute, and open_file. Each one corresponds to a documented REST endpoint, so anything the REST API can do, the MCP server can do, and vice versa. Once you understand this surface, the question of how to connect Obsidian to AI agents reduces to “which MCP client do I want talking to this server.”
Connect Claude Code to Your Vault
Claude Code has native HTTP MCP support. The quickest way to add the Local REST API server is via the CLI, with the API key from your plugin settings.
claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
--header "Authorization: Bearer <your-api-key>"Substitute your real API key. The command stores the server in your user-scoped MCP config so it follows you across projects. If you’d rather scope it to a single vault, run the same command inside the vault directory and Claude Code will write a project-scoped .mcp.json instead. The same config can be hand-written or committed to a repo for collaborators, and it looks like this.
{
"mcpServers": {
"obsidian": {
"type": "http",
"url": "https://127.0.0.1:27124/mcp/",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}
}
}The first time you launch Claude Code with the new server, it will warn you about the self-signed certificate because the connection is HTTPS. You have three ways to handle that warning. Trust the certificate by downloading it from https://127.0.0.1:27124/obsidian-local-rest-api.crt and adding it to your OS trust store, configure your MCP client to skip TLS verification for 127.0.0.1, or enable the plugin’s HTTP endpoint under Settings → Local REST API → Enable HTTP server and point your client at the plain http://127.0.0.1:27123/mcp/ instead. The HTTP endpoint is documented as insecure and disabled by default, so treat it as a last resort for clients that genuinely can’t handle the self-signed cert.
Connect Cursor to the Same Vault
Cursor uses a similar MCP server config. Open Cursor → Settings → MCP, click Add new global MCP server, and paste the same JSON shape. The server URL stays https://127.0.0.1:27124/mcp/, the header stays Authorization: Bearer <your-api-key>, and the server name stays whatever you want Cursor to call it. After Cursor restarts, the vault_* and search_* tools should appear in the model’s tool list. If they don’t, the most common cause is a stale API key. Generate a new one under Settings → Local REST API and paste it again. The path for how to connect Obsidian to AI agents through Cursor is identical to Claude Code on the Obsidian side; only the client config location changes.
Connect Claude Desktop Through mcp-remote
Claude Desktop doesn’t natively support remote HTTP MCP servers, but the project’s README documents a clean bridge using mcp-remote. You’ll need Node.js installed for this. If your goal is specifically how to connect Obsidian to AI agents through Claude Desktop rather than Claude Code, this is the only step that changes.
Edit claude_desktop_config.json. On macOS that’s ~/Library/Application Support/Claude/claude_desktop_config.json, and on Windows it’s %APPDATA%\Claude\claude_desktop_config.json. Add a server entry.
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": [
"mcp-remote@latest",
"https://127.0.0.1:27124/mcp/",
"--header",
"Authorization: Bearer <your-api-key>"
]
}
}
}Restart Claude Desktop. The first run of mcp-remote will warn about the self-signed certificate. Pass --allow-http or --trust-proxy-headers if needed, or use the HTTP fallback endpoint at port 27123 the same way as with Claude Code. Once it’s running, the same vault_* and search_* tools appear in the Claude Desktop tool list.
What Useful Workflows Look Like Once It Works
The point of figuring out how to connect Obsidian to AI agents isn’t the connection itself. It’s the workflows you can build on top of it. Once the MCP server is up, the same primitives show up everywhere: read, write, patch, search, run command, open file. The interesting work is composing those primitives into jobs you actually want done.
Once you understand how to connect Obsidian to AI agents, the practical question becomes which daily job you want to delegate first. The five workflows below are the ones I’d build in order, from lowest risk to highest leverage. Each one reuses the same primitives you just installed, so the cost of trying them is roughly the cost of a single daily note.
Daily notes that write themselves. Tell Claude Code to read your last seven daily notes, summarize recurring themes, and append a “carryover” section to the active daily note. It uses active_file_get_path to find what’s open, vault_read on the previous notes, and vault_append (or a targeted vault_patch on a heading) to write the new content.
Vault-wide search with structured filters. Use search_query with a JsonLogic filter that matches, for example, every note with the tag #research and a frontmatter status: open. That’s something Obsidian’s native search can struggle with on large vaults, and the structured path makes the results predictable.
Targeted patches. Use vault_patch with targetType: heading and an operation like append to add a single line under a specific heading in an existing file. This is how you keep a research note’s “Open Questions” list current without ever rewriting the rest of the document.
Obsidian commands from an agent. command_list and command_execute let an agent trigger commands registered by other plugins, including Templater inserts, Dataview refreshes, or QuickAdd captures. The README notes that command_execute gives access to over two dozen commands when you count the ones shipped by community plugins.
Periodic note round-trips. The REST API exposes /periodic/{period}/ for daily, weekly, monthly, quarterly, and yearly notes, and the MCP server exposes periodic_note_get_path. An agent can fetch today’s daily note path, read it, write structured frontmatter, and move on, all without you typing a filename.
Troubleshooting the Connection
Most problems people hit when learning how to connect Obsidian to AI agents trace to one of five causes. Run through them in order. This checklist is also the right starting point for any agent workflow that suddenly stops working, because the failure modes rarely change.
The plugin isn’t enabled. If the Local REST API section doesn’t appear in Settings, the plugin isn’t installed or isn’t turned on. Restart Obsidian after toggling it.
The API key is wrong. Regenerate it under the plugin settings and re-run claude mcp add with the new value, or update the JSON snippet. The plugin shows the current key in plain text, so this is easy to verify visually.
The certificate is rejected. The HTTPS warning is expected. Trust the certificate, configure your client to skip TLS for 127.0.0.1, or switch to the HTTP fallback endpoint.
The Obsidian app is closed. The plugin runs inside Obsidian, not as a standalone server. If Obsidian isn’t running, nothing is listening on port 27124. Most MCP clients report a clean connection failure when that’s the case.
The vault path is wrong in client commands. The plugin reads paths relative to the active vault’s root. If your MCP client is asking for /Users/me/notes/Projects/foo.md and the active vault is /Users/me/notes, the path the plugin expects is Projects/foo.md. This trips up every first-time user, and it’s the single most common cause of “the connection works but the agent can’t see my files” tickets. Whenever you wonder how to connect Obsidian to AI agents without path drama, the answer is always “open the vault Obsidian considers active and pass paths from its root.”
What This Setup Doesn’t Do
It’s worth saying what this way to connect Obsidian to AI agents does not do, because the boundary is part of why this approach is interesting.
It does not upload your vault anywhere. The plugin is a local server. The MCP client connects to 127.0.0.1. If you also use Obsidian Sync or another cloud sync product, that’s a separate decision and not affected by the plugin.
It does not change how the vault is stored. Notes are still plain Markdown files in a folder on disk. The plugin is an interface, not a database. You can stop using it, remove the plugin, and your vault is exactly as you left it.
It does not give the agent free rein over your filesystem outside the vault. The plugin only sees the active vault’s folder. An MCP client that tries to use vault_read with a path outside the vault gets an error, not a leak.
It does not replace careful editing. The plugin makes an agent a faster editor, not a better thinker. You still want to read the diff before you accept a patch on a long-running research note.
Where to Go From Here
If you’ve followed this far, your vault is now addressable by Claude Code, Cursor, or any MCP client that speaks Streamable HTTP, and you have a complete recipe for how to connect Obsidian to AI agents without losing custody of your notes. The next move is the same one I’d suggest for any new agent capability: pick one workflow you actually run by hand, and have an agent take it over for a week. Daily note carryovers are the easiest first win because the input and output are bounded, the failure modes are obvious, and the daily rhythm catches mistakes early. Once that one is solid, the rest of the workflows above are variations on the same primitives.
Most readers who finish this guide already know how to connect Obsidian to AI agents in principle. The work after that is the workflow design: which jobs are bounded, which are risky, which need a human approval step before the agent writes anything. The plugin gives you every primitive you need; the discipline is in how you compose them.
For a broader tour of how an agent-driven workflow looks in production, the Hermes Agent guide on automating your workflow with Hermes covers the surrounding automation patterns that complement a vault-connected setup. If you’re choosing between MCP-aware clients, the Claude Code setup, workflows, and pro tips guide walks through the same claude mcp add pattern this guide uses, and the OpenAI Codex complete guide is the alternative if you prefer an OpenAI-native workflow.
The plugin’s README on GitHub documents every endpoint, every MCP tool, and the supported patch operations. Obsidian’s help site is the canonical reference for how vaults and notes are structured. If you hit a wall that this guide doesn’t cover, the project’s GitHub issues are active and the maintainer is responsive.
Frequently Asked Questions
Does this work with Obsidian Sync?
Yes. Obsidian Sync handles the vault replication between machines, and the Local REST API plugin runs on whichever machine the agent is connecting to. Each machine needs its own API key, and you can use distinct keys for each client if you want to revoke one without disturbing the others. This is also why how to connect Obsidian to AI agents in a multi-device setup is a per-machine decision rather than a global one.
Can the agent read notes that are inside an encrypted vault?
No. The plugin only sees files that are accessible to the active vault. Encrypted vaults hide their contents from the Obsidian process itself, so the plugin has nothing to serve. Open the vault with its passphrase first if you want the agent to see those notes.
Will this upload my notes anywhere?
No. The plugin is a local HTTP/HTTPS server bound to 127.0.0.1 by default. The MCP client connects to that loopback address. Nothing leaves your machine unless you’ve separately configured Obsidian Sync, Git, or another remote that touches the same files. That local-first posture is one of the main reasons people choose this approach when they want to know how to connect Obsidian to AI agents without giving up custody of their notes.
Can I scope the agent to a single folder inside my vault?
Not directly. The plugin exposes the entire active vault. The clean workaround is to make the subfolder its own vault by moving it to a new directory and opening it as a separate vault in Obsidian. Then the plugin only sees that folder’s tree.
Does this conflict with other Obsidian plugins?
It can if another plugin also opens an HTTP server on the same machine, but Obsidian plugins don’t share ports by default. If you see a port conflict on 27124 or 27123, change the binding port under the Local REST API settings to a free one. Once that’s done, the rest of how to connect Obsidian to AI agents is unchanged: the same MCP server, the same tools, just a different port number in your client config. If you regularly switch between two MCP-aware clients on the same machine, this is also the cleanest way to keep both attached to the same vault without one breaking the other.
