Obsidian MCP: How to Connect Your Vault to Any AI Tool
Your vault holds everything — notes, decisions, half-finished thinking, the reference material you actually trust....
Your vault holds everything — notes, decisions, half-finished thinking, the reference material you actually trust. Your AI tools hold none of it. So you copy-paste the relevant notes into Claude, or describe them to ChatGPT, or just accept that the assistant is guessing at things you already wrote down.
Obsidian MCP closes that gap. It turns your local vault into something an AI tool can read, search, and edit directly — no clipboard, no manual export. The setup is more involved than a plugin install, and a few things reliably break. Here's the whole path.
What is Obsidian MCP?
Obsidian MCP is a setup that exposes your vault to AI tools through the Model Context Protocol, so an assistant can query and modify your notes as structured tools rather than raw files. MCP is the open standard AI tools use to connect to external data; adoption has moved fast, with the official Model Context Protocol project reporting over 97 million monthly SDK downloads and more than 10,000 active MCP servers as of its December 2025 update. Obsidian became one of those servers through the community.
The connection has two parts. First, the Local REST API plugin runs a small HTTP server inside Obsidian that exposes your vault over an authenticated endpoint. Second, an MCP server wraps that API and presents it to AI clients as callable tools — search_vault, get_file_contents, patch_content, and so on. The AI never touches your disk directly; it calls tools, and the plugin does the file work.
That indirection is the point. It's what lets a browser-based tool like ChatGPT reach a vault sitting on your laptop, and it's what makes heading-level and block-level edits possible instead of blind file overwrites.
Which Obsidian MCP servers should you use?
Two options cover almost everyone, and the right one depends on how much you want to install.
Local REST API's built-in MCP server
The coddingtonbear/obsidian-local-rest-api plugin now ships its own MCP server endpoint, served at https://127.0.0.1:27124/mcp/ using Streamable HTTP transport with bearer-token auth. This is the lowest-friction path: one plugin, no separate process to run. If you're connecting a client that speaks Streamable HTTP, start here.
mcp-obsidian
MarkusPfundstein/mcp-obsidian is a standalone MCP server that wraps the same Local REST API. You run it as a separate process, and it's the more common choice for clients that expect a stdio-launched server — Claude Desktop being the obvious one. It exposes granular tools for searching, reading, appending, and patching notes.
When to pick which: if your client wants a command to launch (stdio), use mcp-obsidian. If your client can hit an HTTP endpoint directly, the plugin's built-in server saves you a moving part. Both depend on the Local REST API plugin being installed and running either way.
How do you set up the Local REST API plugin?
Install the plugin, generate an API key, and note the ports — that's the foundation every path below builds on.
- In Obsidian, open Settings → Community plugins, search for Local REST API, install and enable it.
- Open the plugin settings and copy the API key it generates. Every MCP client authenticates with this as a bearer token.
- Note the two endpoints. By default the plugin runs HTTPS on port 27124 with a self-signed certificate, plus an optional plaintext HTTP server on port 27123. Enable the HTTP one — you'll likely need it.
That self-signed certificate is the source of most setup pain, which is why the plaintext fallback exists. Keep both ports in mind; the fix for a stuck connection is often just switching which one you point the client at.
How do you connect it to Claude Desktop vs ChatGPT?
This is where the paths diverge, and the split is the same local-versus-remote transport distinction that governs any MCP connection. A desktop app can reach localhost. A tool running in someone else's cloud cannot.
Claude Desktop (local transport)
Claude Desktop launches MCP servers locally, so you connect over stdio or localhost HTTP by editing claude_desktop_config.json. Add an entry that launches mcp-obsidian, passing your API key and the vault's host and port as environment variables. Restart Claude Desktop, and the vault tools appear. Because everything stays on your machine, there's no tunnel and nothing exposed to the internet — the cleanest version of this setup.
ChatGPT (remote transport)
ChatGPT in a browser runs in OpenAI's cloud, so it can't see 127.0.0.1 on your laptop. To connect it, you expose your local MCP server through a public HTTPS proxy — a Cloudflare Tunnel or Tailscale — and register that public URL as a remote MCP server in ChatGPT. This is the same remote-transport pattern covered in Can Codex Use What You Told ChatGPT? and the broader MCP mechanics in How to Connect an LLM with MCP: local tools need a public front door before a cloud tool can knock on it.
The tradeoff is real. Local transport is private and simple. Remote transport reaches more tools but adds a tunnel you have to secure, keep running, and trust.
What breaks — and how to fix it?
Three failure modes account for most of the "it won't connect" reports, and each has a specific cause.
- Self-signed certificate rejection. Many MCP clients refuse the self-signed HTTPS cert the plugin generates on port 27124. The fix is to point the client at the plaintext HTTP endpoint on 27123 instead, or install the plugin's certificate as trusted on your system.
- Tool collisions with native connectors. If Claude's built-in filesystem connector is also active, its tools can overlap or conflict with the vault's — the model gets two ways to read files and picks wrong. Disable the connector you don't need for this workflow.
- Mobile and local-network resolution. MCP clients on a phone, or on a different device from the vault, can't resolve a
localhosttransport at all. These setups require the remote-tunnel path, not the local one.
There's also a quieter failure: config drift. Rename the vault, rotate the API key, or move machines, and every client config referencing the old values silently stops working. Each tool you've wired up is a separate file to update by hand.
For deeper single-client walkthroughs, Obsidian for Claude covers the browser and desktop bridge, and Obsidian for Claude Code covers the terminal.
Where does a vault MCP stop — and what's next?
A vault MCP connects one vault to one tool at a time, and that's exactly its ceiling. You did the work — plugin, server, config, maybe a tunnel — and the result is that this client can now read your notes. The next tool you adopt starts from nothing: another config file, another decision about local versus remote, another certificate to trust. The setup doesn't travel, and neither does what your AI learned from the vault.
That's fine when Obsidian is a knowledge store you're querying. It's a poor fit for the other thing people actually want, which is for every AI tool to know who they are — role, current projects, how they work — without a per-tool wiring job each time. A vault MCP can't deliver that, because it's built around one folder on one machine, maintained by hand. The distinction is worth reading in full: Obsidian for AI Context vs a Dedicated Context Layer.
Unabyss handles the layer a vault MCP can't. It extracts your context from the sources where it already lives, structures it into a profile you own, and serves it to every MCP-compatible tool at once — so you set it up once instead of re-wiring each tool, and it stays current instead of drifting. Obsidian remains your knowledge base. The context layer is what tells every tool who's asking.
Connect your context once, and every AI tool reads it → Get started free
