obsidian-vault-mcp

A filesystem-based MCP server for Obsidian vaults. Works when Obsidian is closed.

The problem

Every existing Obsidian MCP connector requires Obsidian to be running and the Local REST API plugin active. When Obsidian goes to the background or is closed, the connector drops — silently, mid-session.

Related MCP server: obsidian-mcp-complete

The solution

This server reads and writes your vault directly from disk via Node's fs module. No Obsidian process required. No plugin dependencies. No background disconnects.

Tools

• list_vault_files — list vault files, optionally filtered by directory

• get_vault_file — read a file's content

• append_to_vault_file — append content (creates file and dirs if needed)

• create_vault_file — create or overwrite a file

• patch_vault_file — insert/replace content relative to a heading

• search_vault_simple — plain-text substring search across all notes

patch_vault_file supports three operations relative to any heading:

• append — add content after the heading's section

• prepend — add content immediately after the heading line

• replace — replace the entire heading section with new content

Install

Option A — Double-click install (recommended)

Download obsidian-vault-mcp.mcpb from the latest release and double-click it. Claude Desktop handles the rest.

Option B — Build from source

Requires Node.js 18+.

git clone https://github.com/WhiteWolf-Cyber/obsidian-vault-mcp cd obsidian-vault-mcp npm install npm run build

Claude Desktop config

Add to mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json:

macOS / Linux

{ "Obsidian Vault": { "command": "node", "args": ["/absolute/path/to/obsidian-vault-mcp/dist/index.js"], "env": { "OBSIDIAN_VAULT_PATH": "/Users/yourname/ObsidianVault" } } }

Windows

{ "Obsidian Vault": { "command": "node", "args": ["C:\Users\yourname\dev\obsidian-vault-mcp\dist\index.js"], "env": { "OBSIDIAN_VAULT_PATH": "C:\Users\yourname\Documents\ObsidianVault" } } }

Restart Claude Desktop after saving.

Vault path

The vault path resolves in this order:

1. OBSIDIAN_VAULT_PATH environment variable

2. ~/ObsidianVault (fallback)

Security

Paths are validated at runtime — requests that resolve outside VAULT_PATH are rejected. The server never traverses above the vault root.

Mobile setup (remote access via Cloudflare Tunnel)

The same 21 vault tools are also served over HTTP/SSE so Claude on iOS/iPad can reach your vault as a custom connector. This is purely additive — the stdio transport above continues to work unchanged for Claude Desktop.

1. Install cloudflared: brew install cloudflare/cloudflare/cloudflared

2. Authenticate with Cloudflare: cloudflared tunnel login

3. Create the tunnel: cloudflared tunnel create obsidian-vault-mcp

4. Copy the tunnel UUID printed by the previous command into cloudflare-tunnel.yml (replace <tunnel-id> in the credentials-file path).

5. Set VAULT_MCP_SECRET in your environment (or skip this and let the server generate one — it will print it to stderr on first run, copy it from there).

6. Start the HTTP server: npm run start:http

7. Run the tunnel: cloudflared tunnel run obsidian-vault-mcp (or install cloudflared as a launchd service for persistent background operation on macOS — see Cloudflare's launchd service docs for the plist template.)

8. In the Claude iOS/iPad app, add a custom connector:

   • URL: https://vault.envoyagent.app/sse

   • Authorization: Bearer <your VAULT_MCP_SECRET>

Restarting the connector

If the connector seems stuck, the 10-second I/O timeout guard (see withTimeout in src/tools.ts) will surface a clear error instead of hanging silently. To restart the HTTP transport itself:

pkill -f http-server.js
npm run start:http

No Claude Desktop restart is needed — this only affects the HTTP/SSE transport, not the stdio connection Claude Desktop uses.

Env vars

VAULT_MCP_SECRET=<generate with: openssl rand -hex 32 — do not commit>
PORT=3456
OBSIDIAN_VAULT_PATH=/Users/darrellmahrle/dev/vault

Built by

EnvoyAgent — AI-powered outbound voice appointment setting.