Content
# obsidian-multivault-mcp
An MCP server that gives **Claude read/write access to Obsidian vaults that live on a VPS** — built
for **multiple vaults and multiple users** from a single deployment. Everyone shares one server; each
person is routed to their **own private vault** by the passphrase they log in with (HTTP mode) or by
the vault path Claude Desktop launches with (stdio mode). The server runs *on the VPS* with direct
filesystem access to the vaults.
## Features
- **Multi-vault, multi-user** — one server serves many people, each mapped to their own vault. In HTTP
mode everyone adds the *same* connector URL and their distinct login passphrase decides which vault
they get; in stdio mode each Claude Desktop passes its own vault path.
- **Two transports from one codebase** — stdio over `ssh` (Claude Desktop) and an OAuth-protected
Streamable HTTP endpoint (Claude mobile/web/desktop remote connectors).
- **Read/write tools with strict path safety** — vault-relative paths only; `..`, absolute paths,
symlink escapes, and null bytes are rejected; writes limited to an extension allowlist. Optional
`--read-only` and per-user `readOnly`.
- **Self-hosted OAuth 2.1** — passphrase login, PKCE, JWT access tokens, and Dynamic Client
Registration, so no third-party auth service is needed.
- **Single-file deploy** — esbuild bundles everything to one `dist/index.js`; deploy is a one-file copy.
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 vaults on the VPS" setup:
```
Mac VPS (always-on)
┌ Obsidian app ──(obsidian-remote-ssh plugin)── SSH ─▶ Go daemon ─┐
│ ├─▶ a user's 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
```bash
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:
```bash
npm run inspect -- /absolute/path/to/a/vault
```
## Deploy to the VPS
Requires **Node 20+** on the VPS.
```bash
VPS=user@your-vps DEST=obsidian-multivault-mcp ./scripts/deploy.sh
# copies dist/index.js to ~/obsidian-multivault-mcp/index.js on the VPS
```
Smoke-test the remote copy from your Mac (should print a startup line on stderr, then wait):
```bash
ssh user@your-vps node obsidian-multivault-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`:
```json
{
"mcpServers": {
"obsidian-multivault": {
"command": "ssh",
"args": [
"youruser@your-vps",
"node",
"/home/youruser/obsidian-multivault-mcp/index.js",
"/home/youruser/alice-vault"
]
}
}
}
```
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)
203-0-113-10.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://203-0-113-10.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.example.json).
```json
{
"users": [
{ "id": "alice", "passphrase": "a-long-passphrase", "vault": "/home/youruser/alice-vault" },
{ "id": "bob", "passphrase": "a-DIFFERENT-long-passphrase", "vault": "/home/youruser/bob-vault", "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
```bash
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`](DEPLOY.md) for the full, copy-pasteable runbook** — installing Caddy, the
`/etc/obsidian-multivault-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
(`203-0-113-10.sslip.io` → `203.0.113.10`); 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-multivault-mcp.env`. Requires **Node 20+** and **ports 80 + 443 open**.
## Add it in the Claude mobile app
Settings → **Connectors** → **Add custom connector** → paste
`https://203-0-113-10.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.
