MCP server that gives your agent direct, always-on access to your Obsidian vault - no plugin, no Obsidian process required.
Ask Claude (or any other agent) to find everything you've written about a topic, draft a note in the right folder, or triage your inbox - without ever opening Obsidian.
Works whether Obsidian is open or not - reads your vault straight from the filesystem, so your agent isn't blocked when the app is closed.
One vault, many AI tools at once - it runs as an always-on server, so Claude Code and Claude Desktop can talk to the same vault at the same time, sharing one live index.
Finds what you mean, not just what you typed - hybrid search blends keyword ranking and semantic embeddings. Exact phrases surface when precision matters; conceptual queries work when it doesn't.
Read & write notes
- Ask for a note, a section of one, or a note plus everything it links to - in a single call
- Move or rename a note and every
[[wikilink]]pointing to it updates automatically - Delete safely - soft-delete sends notes to
.trash/instead of destroying them - Change one note or batch dozens of moves, deletes, and frontmatter edits in one go
Find & connect
- Search your whole vault by keyword, by meaning, or both at once - with tag, type, and date filters
- Surface notes that should be linked but aren't, so related ideas stop drifting apart
Capture & triage
- Drop in free-form text and have it classified and filed in the right folder for you
- Auto-triage your inbox: move everything above a confidence threshold to where it belongs
- Open or create today's daily, this week's weekly, or this month's monthly note on demand
Runs as a service
- Name and switch between multiple vaults from one server instance
- Connect Claude Desktop through the bundled stdio bridge
- Automatic SQLite index backups with configurable retention
- OpenTelemetry spans per tool call and webhook alerts, plus
/healthand/readyprobes
Downloads the pre-built binary for your platform, walks you through configuration, and optionally installs a background service.
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/videnovnebojsa/vault-mcp/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/videnovnebojsa/vault-mcp/main/install.ps1 | iexTo reconfigure later (vault path, port, etc.):
bash install.sh --configure # macOS / Linux
.\install.ps1 -Configure # WindowsRequires Bun 1.3+.
git clone https://github.com/videnovnebojsa/vault-mcp
cd vault-mcp
bun install
bun run setupbun run setup builds the binary, walks you through configuration, and installs a background service that starts at login - launchd on macOS, systemd on Linux, Task Scheduler on Windows.
Add to .mcp.json in your project root:
{
"mcpServers": {
"vault": { "type": "http", "url": "http://127.0.0.1:3782/mcp" }
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"vault": {
"command": "/path/to/vault-mcp",
"args": ["bridge"],
"env": { "VAULT_MCP_URL": "http://127.0.0.1:3782/mcp" }
}
}
}Replace /path/to/vault-mcp with the actual binary path — typically ~/.local/bin/vault-mcp after a quick install or /usr/local/bin/vault-mcp after a manual install. The vault-mcp server must be running (the background service installed by the setup script handles this automatically).
The claude_desktop_config.json location varies by platform and build — see docs/clients.md. Windows users on the Microsoft Store build of Claude Desktop have it under %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\..., not %APPDATA%\Claude; install.ps1 detects and prints the right path.
curl http://localhost:3782/health
# {"status":"ok","uptimeSeconds":12,...}/health always returns 200; /ready returns 503 until the vault index finishes its initial sync.
Once connected, just talk to your agent in plain language. Try:
- "Find my notes on productivity systems" → hybrid search across your whole vault
- "File this meeting summary" → capture pipeline classifies it and routes it to the right folder
- "What notes should I connect to this one?" → semantic connection finder surfaces related notes
- "Archive these three project notes" → batch move, with every
[[wikilink]]rewritten automatically
See docs/prompts.md for the full prompt cheat-sheet.
All settings live in ~/.config/vault-mcp/.env. The setup script writes this file with your answers and leaves every optional variable commented out with its default; for a manual install, start from .env.example.
To change settings interactively after installation:
bun run configureThis opens a section menu, validates each setting, shows a diff of what will change, and optionally restarts the service. Jump straight to a section with --section <id>:
bun run configure -- --section embeddingsCustom folder structure? vault-mcp defaults to a numbered Zettelkasten-style layout. Run bun run configure -- --section vault-folders to remap the capture pipeline to your own folder names.
To edit the file by hand instead, open ~/.config/vault-mcp/.env and restart the service:
| Platform | Command |
|---|---|
| macOS | launchctl kickstart -k gui/$UID/com.vault-mcp |
| Linux | systemctl --user restart vault-mcp |
| Windows | schtasks /End /TN vault-mcp && schtasks /Run /TN vault-mcp |
bun run test # run test suite
bun run build # compile TypeScript → dist/
bun run lint # biome checkBinary build scripts (require Bun):
bun run build:bun # standalone executable → dist-bin/
bun run scripts/smoke-test.ts # smoke test the built binary against a real vault| Topic | Link |
|---|---|
| Installation options (manual, service) | docs/installation.md |
| Connecting MCP clients | docs/clients.md |
| Example prompts cheat-sheet | docs/prompts.md |
| How hybrid search works | docs/semantic-search.md |
| Full configuration reference | docs/configuration.md |
| Full tool reference | docs/tools.md |
| Feature roadmap & status | docs/roadmap.md |
| Topic | Link |
|---|---|
| Internal module map & data flow | docs/contributing/architecture.md |
| Architectural rules & patterns | docs/contributing/design-standards.md |
| Tooling, lint, test, CI standards | docs/contributing/typescript-standards.md |