Obsidian MCP Server: Connect Your Vault to AI Agents

Steps

1. 01

   Choose your approach

   Two real servers, different trade-offs. obsidian-mcp (npm) reads the vault directory directly — simplest, no plugin, point it at the vault folder. mcp-obsidian (PyPI) talks to Obsidian through its Local REST API plugin — Obsidian must be open, but it goes through Obsidian's own API. Pick direct (A) for simplicity, REST (B) if you want Obsidian itself in the loop.

2. 02

   Option A — obsidian-mcp (direct vault access)

   No plugin needed. The server takes your vault path as an argument. Verify the exact CLI arguments in the package README, then add it to your agent. For Claude Code, use the stdio add command; the server runs on demand via npx.

   # Claude Code (stdio) — pass your vault path after the package name
   claude mcp add obsidian -- npx -y obsidian-mcp /path/to/your/vault
   
   # Verify it connected
   claude mcp list

3. 03

   Option B — mcp-obsidian (via Local REST API plugin)

   In Obsidian, install and enable the "Local REST API" community plugin, then copy its API key from the plugin settings. Run the server with that key in the environment. Obsidian must be running for the REST endpoint to answer.

   # Claude Code — pass the plugin's API key as an env var
   claude mcp add obsidian -e OBSIDIAN_API_KEY=your-rest-api-key -- uvx mcp-obsidian
   
   # (uvx comes with uv: https://docs.astral.sh/uv/ )

4. 04

   Add it to OpenCode or Cursor

   The same server works across agents — only the config format differs. OpenCode uses a local MCP block in opencode.json (command is an array). Cursor uses .cursor/mcp.json with command + args. Swap in whichever server (and args) you chose above.

   // OpenCode — ~/.config/opencode/opencode.json or ./opencode.json
   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "obsidian": {
         "type": "local",
         "command": ["npx", "-y", "obsidian-mcp", "/path/to/your/vault"],
         "enabled": true
       }
     }
   }

5. 05

   Verify the agent can see your notes

   Confirm the server is connected and the tools are exposed, then ask the agent something that requires your vault — e.g. "search my vault for notes about the auth rewrite." In Claude Code run /mcp; in OpenCode run opencode mcp list.

   # Claude Code
   /mcp
   
   # OpenCode
   opencode mcp list

Troubleshooting

obsidian-mcp starts but finds no notes

The vault path is wrong or not passed. Give the absolute path to the vault folder (the directory that contains your .md files / the .obsidian folder), and confirm the exact argument format in the obsidian-mcp README — flags can change between versions.

mcp-obsidian returns connection or 401 errors

The Local REST API plugin must be installed AND enabled, Obsidian must be open, and OBSIDIAN_API_KEY must match the key shown in the plugin settings. The plugin defaults to HTTPS on port 27124 — check its settings if you changed the host/port.

command not found: npx or uvx

obsidian-mcp needs Node.js (npx ships with it). mcp-obsidian needs uv (which provides uvx) — install from docs.astral.sh/uv, or run the server with pip/python instead.