Local REST API plugin not configured. That's the error Claude Desktop throws, three separate times in my case, before its MCP server actually starts talking to an Obsidian vault. Not a crash. The settings pane looks fine, sits there looking perfectly reasonable, while the API key field is empty. The plugin's own documentation lists the Local REST API dependency as required, but nothing in the setup flow tells you that skipping it leaves every call failing silently or timing out. On a vault of roughly four thousand markdown files, that same gap between what the docs promise and what actually happens shows up again, this time as an indexing delay long enough that force quitting Obsidian starts to feel like a reasonable life choice. So here's the question actually worth answering: does this plugin's behavior match what the documentation promises, and where exactly does it fall short?
Obsidian MCP Tools, built by jacksteamdev, is a two part system: an Obsidian plugin plus a local MCP server binary that bridges your vault to any MCP compatible client, Claude Desktop being the obvious one. The pitch is straightforward. Semantic search across your notes, Templater prompt execution, and note reading all run through a server that never hands the AI direct filesystem access. Getting there is where the friction lives, and it's where most writeups stop short of telling you what actually breaks.
Readers Assume Vault Access Means Pointing at a Folder
Obsidian MCP Tools Setup Flow
Skipping Step 1 or 2 lets Steps 3 to 5 appear to succeed while every call fails silently or times out.
Source: Based on article description of setup process
The assumption, reasonable on its face, is that giving Claude access to your Obsidian vault means pointing it at a folder. Markdown files are just text, after all. Why would you need a plugin, a server process, and a REST API key just to let a language model read a directory of files?
The setup tells a different story. Obsidian MCP Tools depends on the Local REST API community plugin as a hard prerequisite, not an optional integration. You install that plugin first, generate an API key inside its settings tab, and only then does Obsidian MCP Tools have something to authenticate against. Skip that step and the MCP server installs cleanly, Claude Desktop even lists the tools, and every call fails silently or times out anyway. Without the key there's no bridge, just two disconnected pieces that look connected.
- Semantic search across notes
- Templater prompt execution
- Note reading through an authenticated endpoint
This architecture exists for a reason, and it's the same reason it feels heavier than expected. A raw filesystem mount gives an AI client read and write access to everything, no audit layer, no consent step. The REST API plugin, combined with the MCP server acting as a gatekeeper, routes every read, every semantic search, and every Templater execution through an authenticated local endpoint that Obsidian itself runs and can log. A vault full of personal journal entries doesn't turn into an open file share the moment you approve an MCP connection in Claude's settings.
That authentication requirement is the first place setup actually breaks: three failed connection attempts before most people find the missing API key field.
The Local Server Model Changes How Debugging Works
Filesystem Mount vs MCP Tools Architecture
| Aspect | Raw Folder Mount | MCP Tools + REST API |
|---|---|---|
| Access scope | Full read and write | Scoped to defined tools |
| Authentication | None | API key required |
| Audit / logging | None | Logged via local endpoint |
| Consent step | None | Explicit connection approval |
| Setup complexity | Low | High (plugin + server + config) |
Source: Based on article's architecture comparison
Once the API key is in place, the next source of failure isn't authentication, it's process management. If you've worked with hosted MCP servers, you're used to a certain kind of failure: auth token expired, rate limit hit, network blip. Obsidian MCP Tools fails differently because the server runs on your machine, spawned as a subprocess that Claude Desktop launches based on its local configuration file. That file is claude_desktop_config.json, and it's usually where things go sideways.
{
"mcpServers": {
"obsidian-mcp-tools": {
"command": "/Users/yourname/.obsidian-mcp-tools/bin/mcp-server",
"args": [],
"env": {
"OBSIDIAN_API_KEY": "your-generated-key-here",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}
}
}
The installer writes this file for you when everything goes right. When it doesn't, you end up hand editing paths on Windows, where backslashes need escaping, or discovering the port in this file doesn't match the port the Local REST API plugin is actually listening on, because you changed it once, months ago, for some unrelated reason and forgot.
Restarting Claude Desktop doesn't reliably restart the spawned MCP server subprocess on every platform, either. On macOS, I've seen stale server processes hang around after an update, still bound to the old port, refusing to let go. The fix isn't pretty.
ps aux | grep mcp-server
kill -9 <pid>
Then relaunch Claude Desktop and let it spawn a fresh process. You won't find this in the plugin's README, because it's not really the plugin's fault. It's what happens when Obsidian, its REST API plugin, a Node based MCP server, and an Electron app all need to agree on the same port number: three separate processes, one shared port, zero tolerance for drift.
Semantic Search Performance Depends on Vault Scale
Where Setup Actually Breaks
Source: Based on article's failure points
With the connection stable, the next variable is vault size, and this is where the plugin's core feature starts behaving differently than the pitch suggests. The semantic search feature is the one people install this plugin for, and it's also the one with the least predictable performance depending on how big your vault is. The plugin builds an embedding index over your notes, stored locally, and Claude queries against that index instead of doing naive keyword matching.
For a vault under a thousand notes, indexing finishes in the background without you noticing. Past that, the numbers change. I run roughly four thousand markdown files, mostly short daily notes plus a few hundred longer reference documents, and the initial indexing took long enough that I force quit Obsidian, assuming it had stalled, before learning better.
Semantic search quality is tied directly to how consistently your notes are tagged and structured, not just their raw content. A vault full of untitled daily notes with no frontmatter returns mushier, less precise results than one where notes have consistent headers and tags. This is a known trait of embedding based retrieval in general, nothing specific to this plugin, but it only shows up once you're querying your own messy vault instead of a demo one.
Compare that to the brute force alternative: copy pasting note contents directly into a Claude conversation.
- No indexing delay
- No dependency chain
- No port conflicts
- No persistence across sessions
- No Templater integration, which is really the whole reason to go through the setup pain in the first place
One approach scales with vault size and gets more useful the more notes pile up. The other stays exactly as tedious no matter how good the notes are. Four thousand notes is roughly where that difference stops being theoretical and starts being your afternoon.
Templater Integration: Worth the Added Complexity?
Search explains why people install the plugin. Templater execution is the feature that decides whether they keep using it, and it gets undersold in most descriptions of this plugin, probably because it's harder to demo than search. Claude can trigger a Templater template inside your vault, one that might prompt for input, generate a new note with a specific structure, or run JavaScript that touches other files in the vault.
That's genuinely different from asking Claude to just hand you markdown text. A Templater script with tp.system.prompt() calls or file system operations executes inside Obsidian's own environment, with Obsidian's own permissions, triggered remotely by an MCP tool call. That's a meaningfully different security surface than read only semantic search, and it's why the plugin's documentation is explicit that this bridge only works when deliberately allowed, never as a default.
In practice, it earns its place for one narrow thing: a weekly review template Claude can trigger after summarizing the week's daily notes, generating a structured note with sections already populated from what Claude found. It works. It also fails in one specific way worth flagging.
# not actual plugin code, but the shape of the failure
when a Templater script expects synchronous user input
and the MCP call has no interactive terminal to route it through
def run_templater_prompt(template_path):
result = call_mcp_tool("execute_template", {"path": template_path})
if result.get("status") == "timeout":
# tp.system.prompt() has no interactive session to attach to
# over the MCP bridge, so it hangs until Obsidian's own timeout fires
raise RuntimeError("Template requires interactive input, unsupported over MCP")
Templates needing tp.system.prompt() style interactive input have nowhere to route that prompt when triggered remotely through MCP. They hang or fail depending on how the template's written. Templates built for unattended execution work fine. Templates built assuming a human sits at the keyboard don't translate, and Claude Desktop gives you no error message that makes this obvious. A timeout is all you get; the real explanation lives in Obsidian's own template execution logs.
Templates aimed at Claude need a different design discipline than the ones you'd write for a hotkey at your own desk.
One Version Number Blocks Everything Else
Everything above, the API key, the port matching, the indexing time, the Templater behavior, assumes the underlying Obsidian install can actually run this plugin. That assumption is the last thing worth checking, and most setup guides bury it in a footnote as if any recent Obsidian install will do. Wrong often enough to matter.
The plugin's documentation lists Obsidian v1.7.7 as the minimum required version. Earlier versions don't expose the plugin API surface this integration depends on, so an outdated Obsidian install is a common reason the whole chain fails before the REST API key even comes into play. Obsidian doesn't always force updates the way some apps do, so checking Settings, About, and comparing against v1.7.7 directly saves you a debugging session that otherwise looks exactly like an API key problem or a port conflict.
That's the actual gap between the pitch and the setup: not that Obsidian MCP Tools fails to do what it promises, but that reaching working semantic search and Templater execution means clearing four separate failure points, an unset API key, a mismatched port, an indexing delay at scale, and an unmet version requirement, none of which the documentation sequences for you. Check v1.7.7 first, generate the API key second, confirm the port third, and expect the index to take real time on a vault of thousands of notes. Do it in that order, and the setup that looked broken turns out to just be underdocumented.