vault-bridge

# Vault Bridge

Bridge your AI assistant to local knowledge vaults — read, write, search, and manage notes without cloud dependencies.

Default mode: local stdio connector (no listening port). Vault content stays on the path you configure.

Non-technical readers (COLP / practice manager / firm IT): start with CLIENT-README.md - install, privacy boundary, verify, uninstall, and support without developer jargon.

Features

• read_note — Read a note with optional frontmatter parsing

• write_note — Write notes with YAML frontmatter support

• list_notes — List notes with glob filtering and recursion

• search_notes — Regex search across vault content

• search_frontmatter — Query notes by frontmatter key/value

• get_daily_note — Get or create daily notes with templates

Related MCP server: obsidian-codex-mcp

Installation (Windows — recommended)

One command from the product tree (UNSIGNED INTERNAL until Authenticode is available):

powershell -ExecutionPolicy Bypass -File .\installer\Install-VaultBridge.ps1 -VaultPath "C:\Path\To\Your\Vault"

Silent (firm IT):

powershell -ExecutionPolicy Bypass -File .\installer\Install-VaultBridge.ps1 -VaultPath "C:\Path\To\Your\Vault" -Quiet

Post-install smoke (JSON-RPC; fails loudly):

powershell -ExecutionPolicy Bypass -File .\scripts\self_test.ps1 -VaultPath "C:\Path\To\Your\Vault"

Details: installer\README.md. Zero-egress proof pack: proof-pack\README.md (see also proof-pack\DEMO-CHECKLIST.md).

Signing: builds produced without an Authenticode certificate are labelled UNSIGNED INTERNAL. See proof-pack\SIGNING.md.

Advanced — pip / uv (developers)

pip install vault-bridge
# (some indexes may still show airgap-vault-bridge)
# or, from a checkout with uv.lock:
uv sync --frozen

Usage

CLI (Direct)

vault-bridge

MCP Client Config (Claude Desktop, Cursor, VS Code)

Prefer the Private Desk / installer local path over uvx for air-gapped desks:

Windows (requires full path to executable):

{
  "mcpServers": {
    "vault-bridge": {
      "command": "C:\\Users\\YOU\\AppData\\Local\\AirgapFleet\\vault-bridge\\bin\\vault-bridge.cmd",
      "env": {
        "OBSIDIAN_MCP_VAULT_PATH": "C:/path/to/vault",
        "OBSIDIAN_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

macOS/Linux (if on PATH):

{
  "mcpServers": {
    "vault": {
      "command": "vault-bridge",
      "env": {
        "OBSIDIAN_MCP_VAULT_PATH": "/path/to/vault"
      }
    }
  }
}

DXT (Claude Desktop 1-Click)

Download airgap-vault-bridge-1.0.2.dxt from Releases → drag into Claude Desktop.

Configuration

Runtime settings use the OBSIDIAN_MCP_ environment prefix (see src/obsidian_mcp/models.py).

Tool Reference

read_note

{
  "path": "Projects/roadmap.md",
  "include_frontmatter": true
}

write_note

{
  "path": "Projects/new-idea.md",
  "content": "# New Idea\n\nDetails here...",
  "frontmatter": { "tags": ["idea", "draft"], "status": "wip" }
}

list_notes

{
  "path": "Projects",
  "glob_pattern": "**/*.md",
  "recursive": true
}

search_notes

{
  "pattern": "MCP",
  "path": ".",
  "max_results": 50
}

search_frontmatter

{
  "key": "status",
  "value": "done",
  "operator": "eq"
}

get_daily_note

{
  "date": "2026-08-21",
  "folder": "Daily Notes",
  "create_if_missing": true
}

Windows-Specific Notes

• Preferred install path after Private Desk installer: %LOCALAPPDATA%\AirgapFleet\vault-bridge\bin\vault-bridge.cmd (avoid legacy Hermes venv paths for pilots)

• Always use the full .exe path in MCP client configs on Windows — bare commands like vault-bridge will fail with ENOENT because the venv Scripts folder is not on system PATH

• Use forward slashes in environment variable values (C:/path/to/vault) — they work fine in JSON

• Escape backslashes in JSON command paths (C:\Users\...)

License

MIT