Guides and resources for AI engineers: an agents course, five handbooks, a hands-on second-brain project and a vetted reading list.
MCP for Obsidian
MCP is the standard way Claude talks to other applications. For a vault, it adds a door into Obsidian itself rather than into the folder underneath, which means the agent can work with the vault from any session, not only one started inside that directory.
You do not need this to start. Add it when you want scheduled tasks, or when you are working from the desktop app rather than a terminal in the vault.
Two routes
The Local REST API
plugin now ships a
built-in MCP server at /mcp/, so a separate server is no longer required.
Check its README first: if the built-in server covers what you need, skip
straight to registering it with your client and ignore step 2 below.
The third-party route described here, mcp-obsidian over the plugin's REST API,
is still the most widely documented and is what most guides describe. Both end
up in the same place.
Step 1: enable the plugin
In Obsidian: Settings (gear, bottom left) → Community plugins → Turn
on community plugins → Browse → search Local REST API → Install →
Enable.
Open the plugin's settings. There is an API Key, a long string of letters and numbers. Copy it.
Obsidian displays the key with the word Bearer in front of it. That word is
not part of the key. Copy only the string after it. This is the single most
common reason the connection fails on the first try.
Step 2: register the server
In the Claude Code tab or terminal, with your key pasted in place of
PASTE-YOUR-KEY-HERE:
claude mcp add-json obsidian-vault '{
"type": "stdio",
"command": "uvx",
"args": ["mcp-obsidian"],
"env": {
"OBSIDIAN_API_KEY": "PASTE-YOUR-KEY-HERE",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}'
uvx runs the server without a permanent install. If the command is not found,
install uv first.
Step 3: test it
List every file in my Obsidian vault.
If the agent reads your notes back, the connection works.
When it does not work
- Obsidian is closed. The plugin serves the API from inside the app, so the connection only exists while Obsidian is running.
Bearerin the key. Strip it.- Wrong port. Check the port shown in the plugin settings against the value in your config. The default is 27124.
- Plugin disabled. Community plugins get turned off when restricted mode is re-enabled after an update.
Do you need this at all
One maintained fork of mcp-obsidian was archived with the reasoning that
routing through a REST plugin adds complexity when a vault is just markdown
files on disk. That is the same argument this guide makes for starting on the
filesystem, and it is worth taking seriously: MCP earns its place when you need
the vault reachable from sessions not running inside it, and not before.
Security
This opens a local HTTP server with a key that grants full read and write access
to your notes. Keep it on 127.0.0.1, never expose the port, and treat the key
like a password. If you paste it anywhere public, rotate it in the plugin
settings.