obsidian-vault-mcp

obsidian-vault-mcp

An MCP server that gives Claude Desktop read/write access to an Obsidian vault that lives on aVPS. The server runs on the VPS with direct filesystem access to the vault; Claude Desktoplaunches it over an ssh stdio pipe. There is no SSH library inside the server — SSH is only thetransport Claude Desktop uses to start it and exchange JSON-RPC.

Part of a "centralise the vault on the VPS" setup:

  Mac                                            VPS (always-on)
  ┌ Obsidian app ──(obsidian-remote-ssh plugin)── SSH ─▶ Go daemon ─┐
  │                                                                 ├─▶  the one vault
  └ Claude Desktop ─(ssh stdio → node index.js)── SSH ─▶ THIS server┘        ▲
                                                                     Hermes agent (direct fs)

Tools

Read: list_notes, read_note, search_notes.Write (disabled with --read-only): write_note, create_note, append_to_note, edit_note,delete_note, move_note.

All paths are vault-relative and confined to the vault root — .., absolute paths, symlinkescapes, and null bytes are rejected; writes/deletes/moves are restricted to allowed extensions(.md, .markdown, .canvas, .txt by default; override with --ext).

Build & test locally

npm install
npm run build            # bundles to dist/index.js (single file)
npm run smoke            # spins up the server against a temp vault and exercises every tool
npm run typecheck        # optional: tsc --noEmit

You can also drive it interactively with the MCP Inspector:

npm run inspect -- /absolute/path/to/a/vault

Deploy to the VPS

Requires Node 20+ on the VPS.

VPS=user@your-vps DEST=obsidian-mcp ./scripts/deploy.sh
# copies dist/index.js to  ~/obsidian-mcp/index.js  on the VPS

Smoke-test the remote copy from your Mac (should print a startup line on stderr, then wait):

ssh user@your-vps node obsidian-mcp/index.js /absolute/path/to/vault
# Ctrl-C to stop

Wire up Claude Desktop (per Mac)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "ssh",
      "args": [
        "user@your-vps",
        "node",
        "/home/user/obsidian-mcp/index.js",
        "/home/user/asep_brain"
      ]
    }
  }
}

Restart Claude Desktop. A second Mac (different vault on the same VPS) uses the same block with thatMac's vault path as the last argument.

Notes:

• ssh must authenticate non-interactively (key auth, no passphrase prompt) — test withssh user@your-vps true.
• Add "--read-only" as a final arg to expose only the read tools.
• Config is passed as CLI args, not env, because ssh does not forward environment variables bydefault.

CLI

node index.js <vault-root> [--read-only] [--ext .md,.canvas] [--http [--port 8787] [--host 127.0.0.1]]

Default (no --http): stdio transport, launched over ssh by Claude Desktop (above).With --http: a long-lived HTTP server for Claude's remote connectors, including themobile app (see below).

Reach it from the Claude mobile app (remote connector)

The mobile app can't use ssh. Like claude.ai / Desktop / Cowork, it connects to remote MCPservers from Anthropic's cloud, over Streamable HTTP to a public HTTPS URL. So the sameserver also runs an HTTP transport (--http) fronted by a self-hosted OAuth 2.1 layer — the sshkey gate is gone once it's public, so a login gate replaces it.

Claude mobile ──HTTPS──▶ Caddy (:443, auto Let's Encrypt)  ─▶  node index.js --http (127.0.0.1:8787)
                          91-99-211-116.sslip.io                 ├ OAuth 2.1 (passphrase login, PKCE, JWT)
                                                                  └ /mcp  (guarded by bearer JWT)  ─▶ vault

The stdio/ssh path for Claude Desktop is unchanged and runs independently.

HTTP-mode configuration (env vars)

--http reads these from the environment:

Multiple people, multiple vaults

Point MCP_USERS_FILE at a JSON file with one entry per person — each distinct passphrase mapsto that person's own vault. Everyone adds the same connector URL in their own Claude account; thepassphrase they log in with is what routes them to the right vault. Seeusers.example.json.

{
  "users": [
    { "id": "asep", "passphrase": "a-long-passphrase",           "vault": "/home/bepitulaz/asep_brain" },
    { "id": "retno", "passphrase": "a-DIFFERENT-long-passphrase", "vault": "/home/bepitulaz/obsidian", "readOnly": false }
  ]
}

In this mode the CLI vault argument is not needed (node dist/index.js --http). Optional per-userkeys: readOnly and ext.

Test HTTP mode locally

npm run build
npm run smoke:http           # spins up two servers: tools-over-HTTP + full OAuth handshake

# Or drive it by hand (auth disabled) with the MCP Inspector:
MCP_NO_AUTH=1 node dist/index.js /path/to/vault --http --port 8787
#   → point the Inspector (Streamable HTTP) at http://localhost:8787/mcp

Deploy to a public HTTPS endpoint (VPS)

See DEPLOY.md for the full, copy-pasteable runbook — installing Caddy, the/etc/obsidian-mcp.env secrets, the systemd unit, the Caddyfile, firewall, verification, andtroubleshooting. It's written so an agent with shell access on the VPS can follow it end to end.

In short: sslip.io gives an HTTPS-capable hostname for the bare IP with no domain purchase(91-99-211-116.sslip.io → 91.99.211.116); Caddy terminates TLS on 443 and reverse-proxies to theNode service on 127.0.0.1:8787; the service runs under systemd reading its secrets from/etc/obsidian-mcp.env. Requires Node 20+ and ports 80 + 443 open.

Add it in the Claude mobile app

Settings → Connectors → Add custom connector → pastehttps://91-99-211-116.sslip.io/mcp → leave Advanced settings (Client ID/Secret) blank (theserver supports Dynamic Client Registration) → Add. When prompted, complete the browser loginwith your own passphrase. All tools then appear. Each person adds the same URL in their ownClaude account and logs in with their own passphrase to reach their own vault.

Security notes (the public surface is read + write)

• The passphrase and JWT secret live only in the mode-600 EnvironmentFile. Use a strong passphrase.
• Access tokens are short-lived (1h) JWTs; rotate MCP_JWT_SECRET to revoke everything immediately.
• Run --read-only in the systemd unit if you don't need mobile writes — it shrinks the blast radius.
• Keep the Node service bound to 127.0.0.1; only Caddy faces the internet, over HTTPS.