# 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.

## 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](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/run-as-a-service/macos/)
   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](https://envoyagent.app) — AI-powered outbound voice
appointment setting.