obsidian-vault-mcp

An MCP server that gives Claude Desktop read/write access to an Obsidian vault that lives on a VPS. The server runs on the VPS with direct filesystem access to the vault; Claude Desktop launches it over an ssh stdio pipe. There is no SSH library inside the server — SSH is only the transport 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, symlink escapes, 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 that Mac's vault path as the last argument.

Notes:

• ssh must authenticate non-interactively (key auth, no passphrase prompt) — test with ssh 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 by default.

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 the mobile 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 MCP servers from Anthropic's cloud, over Streamable HTTP to a public HTTPS URL. So the same server also runs an HTTP transport (--http) fronted by a self-hosted OAuth 2.1 layer — the ssh key 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:

Var	Required	Meaning
MCP_PUBLIC_URL	yes	Public origin, e.g. https://91-99-211-116.sslip.io. Used as the OAuth issuer/audience.
MCP_JWT_SECRET	yes	32+ random bytes used to sign access/refresh tokens. Rotating it revokes all tokens.
MCP_USERS_FILE	one of	Per-user {id, passphrase, vault} map (see below) — for multiple people/vaults.
MCP_AUTH_PASSPHRASE	one of	Single-user shortcut: the login passphrase for the one vault given as the CLI arg. Use this or MCP_USERS_FILE.
MCP_CLIENTS_FILE	no	Where DCR client registrations persist (default: next to index.js).
MCP_NO_AUTH	no	Set to 1 to disable auth — local testing only, never public.

Multiple people, multiple vaults

Point MCP_USERS_FILE at a JSON file with one entry per person — each distinct passphrase maps to that person's own vault. Everyone adds the same connector URL in their own Claude account; the passphrase they log in with is what routes them to the right vault. See users.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-user keys: 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, and troubleshooting. 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 the Node 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 → paste https://91-99-211-116.sslip.io/mcp → leave Advanced settings (Client ID/Secret) blank (the server supports Dynamic Client Registration) → Add. When prompted, complete the browser login with your own passphrase. All tools then appear. Each person adds the same URL in their own Claude 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.