obsidian-vault-mcp

Read-only MCP access to an Obsidian vault, straight from the filesystem.

No Obsidian plugin, no REST API, no running Obsidian. The server reads the .md files on disk, so it works when Obsidian is closed, when the vault lives on a synced folder, and on a headless machine.

Why this one

Most Obsidian MCP servers talk to Obsidian itself through the Local REST API community plugin. That is the right design if you want to drive the app — open a note, run a template — but it means the app has to be running, and it puts a plugin in the path of every read.

This server does the opposite: it treats the vault as what it is on disk, a folder of Markdown files, and only reads. That makes it dependable in the cases where the REST-API servers are not available at all, at the cost of not being able to drive Obsidian's UI.

It also searches what the notes say, not just what they are called — search_content and search_meta are the tools that make a vault actually useful to an agent.

Related MCP server: Obsidian MCP Second Brain Server

Install

npm install -g @phssakaigawa/obsidian-vault-mcp

Or run it without installing:

npx -y @phssakaigawa/obsidian-vault-mcp /path/to/vault

Node 18 or newer.

Configure

The server speaks MCP over stdio, so any MCP client can use it. One or more vault directories are passed as positional arguments.

Claude Code

claude mcp add obsidian -s user -- npx -y @phssakaigawa/obsidian-vault-mcp /path/to/vault

Claude Desktop — in claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@phssakaigawa/obsidian-vault-mcp", "/path/to/vault"]
    }
  }
}

On Windows, prefer an absolute path to node.exe plus the installed entry point over npx; it does not depend on PATH and does not lose quoting:

{
  "command": "C:\\Program Files\\nodejs\\node.exe",
  "args": [
    "C:\\path\\to\\node_modules\\@phssakaigawa\\obsidian-vault-mcp\\dist\\index.js",
    "C:\\Users\\you\\Documents\\MyVault"
  ]
}

Any other MCP client — same command / args, in whatever config file it uses.

Tools

All five are read-only and are annotated as such, so clients that offer per-tool auto-approval can safely allow the lot.

Every search takes a limit, and the result says when the limit was the reason it stopped.

Safety

The vault directories given on the command line are the only thing the server will read.

Each requested path is resolved and checked twice: once as written, and again after symlink resolution, so a link inside the vault cannot be used to read a file outside it. Containment is separator-aware — a root of /vault does not admit /vault-private. Relative paths resolve against the vault root, not the process working directory, which for an MCP server is just wherever the client happened to launch it.

There is no write path. Nothing in this server opens a file for writing.

.obsidian, .trash, .git and other dot-directories are skipped, so workspace state and plugin configuration never reach the model.

Design notes

Every runtime import is a declared dependency. There are three — the MCP SDK, zod and yaml — and all three are in dependencies with an explicit range. Relying on a transitive package being hoisted into place works right up until the day the ecosystem moves and the package resolves to a version whose API has changed; the failure then looks like a malformed tool schema rather than a missing module, which is a genuinely confusing thing to debug. Declaring what you import costs one line and removes the whole class of problem.

Searches stream. Traversal is an async generator, so a search that reaches its limit stops touching the disk at that point instead of walking the whole vault first.

Frontmatter goes through a real YAML parser. Frontmatter is arbitrary YAML; a regex approach quietly mis-parses nested maps and multi-line strings. A note whose frontmatter does not parse yields no metadata rather than failing the search it appears in.

Limitations

• Read-only, by design.

• Only .md files. Canvases, attachments and other vault contents are not indexed.

• No semantic or embedding search; search_content is literal and regex matching.

• Wiki-links are not resolved into a graph. [[Note]] is matched as text like any other.

• No index is kept between calls. Searches walk the vault each time, which is fine for vaults in the low thousands of notes and is the reason there is nothing to invalidate when the vault changes underneath you.

Development

npm install
npm run build
node scripts/probe.mjs /path/to/vault

scripts/probe.mjs speaks MCP to the built server and prints what a client would see. It checks the thing every client validates first — that each tool advertises an object inputSchema — then calls each tool and confirms a path outside the vault is refused.

License

MIT. See LICENSE and NOTICE; the vault boundary check is derived from the MIT-licensed Model Context Protocol reference filesystem server, and NOTICE records exactly what was taken and what was changed.