What is this?
vault-cortex gives any MCP client — Claude Desktop, Claude Code, Cursor, OpenCode — full access to your Obsidian vault. Search notes, read and write content, query the link graph, manage structured memory, and resolve daily notes — all through 23 tools over a single Docker container.
The typical Obsidian + MCP setup requires three moving parts running simultaneously: Obsidian open → Local REST API plugin → a separate MCP server wrapping the REST API. vault-cortex replaces all of that with Docker and your vault folder.
- Plugin-free — Obsidian doesn't need to be running; headless sync keeps the vault current, and the server works directly with
.mdfiles on disk - Remote access — works from your phone, a remote server, or any MCP client via OAuth 2.1
- Ranked search — SQLite FTS5 with BM25 scoring, stemming, phrase matching, and tag/property/folder filtering
- Structured memory — dated entries, section targeting, auto-initialization for AI personalization
- Obsidian-native — understands frontmatter, wikilinks, tags, headings, and daily notes
Roadmap
| Phase | What | Status |
|---|---|---|
| 1 | Vault CRUD, full-text search (FTS5), memory layer, OAuth 2.1 | Complete |
| 2 | Semantic search + knowledge graph via LightRAG | Planned |
Quick Start
Local (5 minutes — Docker + your vault folder)
Prerequisites: Docker and an Obsidian vault (or any folder of .md files).
# 1. Get the quickstart files
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/.env.example
# 2. Configure
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN (openssl rand -hex 32) and VAULT_PATH
# 3. Start
docker compose up
Connect Claude Desktop or Claude Code — add a remote MCP server with URL http://localhost:8000/mcp and your token as the bearer token.
Full local guide →
Remote (access from anywhere — Docker + Obsidian Sync)
Run vault-cortex on a VPS with Obsidian Sync for remote access from any device.
# On your VPS:
mkdir -p /opt/vault-cortex && cd /opt/vault-cortex
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/.env.example
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN, PUBLIC_URL, OBSIDIAN_AUTH_TOKEN, VAULT_NAME
docker compose up -d
Connect via OAuth — add a remote MCP server with <PUBLIC_URL>/mcp. A consent page opens; enter your token to approve. JWT access tokens refresh automatically.
Full remote guide →
Tools (23)
| Category | Tool | Description |
|---|---|---|
| Vault CRUD | vault_read_note |
Read a note by path |
vault_write_note |
Create or overwrite a note with frontmatter | |
vault_patch_note |
Heading-targeted edit (append, prepend, replace, insert) | |
vault_replace_in_note |
Find-and-replace text in a note | |
vault_list_notes |
List notes with optional glob/folder filter | |
vault_delete_note |
Delete a note (protected paths enforced) | |
| Search | vault_search |
Full-text search with tag/folder/property filters |
vault_search_by_tag |
Find notes by tag (exact or prefix match) | |
vault_search_by_folder |
Browse notes in a folder with metadata | |
vault_recent_notes |
Recently modified or created notes | |
vault_list_tags |
All tags with usage counts | |
| Memory | vault_get_memory |
Read structured memory (file, section, or all) |
vault_update_memory |
Append a dated entry to a memory section | |
vault_delete_memory |
Remove a specific memory entry by date | |
vault_list_memory_files |
Discover memory files and their sections | |
| Properties | vault_list_property_keys |
All frontmatter keys with sample values |
vault_list_property_values |
Distinct values for a property key | |
vault_search_by_property |
Find notes by frontmatter key-value | |
vault_update_properties |
Add or update properties without touching the body | |
| Links | vault_get_backlinks |
Notes linking to a given path |
vault_get_outgoing_links |
Links from a given note | |
vault_find_orphans |
Notes with no incoming links | |
| Daily Notes | vault_get_daily_note |
Today's (or any date's) daily note |
Configuration
All settings are environment variables with sensible defaults.
| Variable | Required? | Default | Description |
|---|---|---|---|
MCP_AUTH_TOKEN |
Yes | — | Bearer token for authentication (also the JWT signing key) |
VAULT_PATH |
Local only | — | Host path to your vault (bind mount source; remote uses a named volume) |
PUBLIC_URL |
Remote only | — | Public URL for OAuth discovery metadata |
MEMORY_DIR |
— | About Me |
Vault folder for structured memory files |
PROTECTED_PATHS |
— | MEMORY_DIR, Daily Notes |
Folders that vault_delete_note refuses to touch |
ORPHAN_EXCLUDE_FOLDERS |
— | Daily Notes, Templates, MEMORY_DIR |
Folders excluded from orphan detection |
TZ |
— | UTC |
IANA timezone for timestamps and daily note resolution |
SERVICE_DOCUMENTATION_URL |
— | GitHub repo URL | URL returned in OAuth discovery metadata |
LOG_LEVEL |
— | info |
Logging verbosity: debug, info, warn, error |
LOG_DIR |
— | /data/logs (Docker) |
Directory for persistent log files. Logs survive container restarts. |
LOG_RETENTION_DAYS |
— | 30 |
Days to keep log files before automatic cleanup on startup |
Smart defaults: Setting MEMORY_DIR automatically updates the defaults for PROTECTED_PATHS and ORPHAN_EXCLUDE_FOLDERS. You only set those explicitly for a fully custom list.
See templates/memory/ for memory file examples and the dated-entry design philosophy.
Authentication
Two methods, both validated at two layers (Lambda authorizer + Express middleware):
| Method | Used by | Token format |
|---|---|---|
| OAuth 2.1 | Claude Desktop, Claude Code, claude.ai, any OAuth client | JWT (HS256, 24h) |
| Static bearer | Claude Code, MCP Inspector, curl | Raw MCP_AUTH_TOKEN |
OAuth uses dynamic client registration — no Client ID/Secret needed. A consent page opens in your browser; enter your MCP_AUTH_TOKEN to approve. Refresh tokens have a 60-day sliding expiry (daily users never re-authenticate).
See ARCHITECTURE.md → Auth for the full flow diagram.
How It Works
graph LR
Client["MCP Client"] -->|OAuth 2.1 / Bearer| Server["vault-mcp"]
Server -->|read/write| Vault[("/vault<br/>.md files")]
Server -->|query| SQLite[("SQLite FTS5")]
Sync["obsidian-sync"] <-->|Obsidian Sync| Vault
The vault .md files are the source of truth. SQLite FTS5 is rebuildable derived state — the index is built on startup and kept current by a file watcher. obsidian-sync keeps the vault in sync with your Obsidian apps (remote deployments only).
See ARCHITECTURE.md for the full design, auth flow diagrams, and Phase 1/2 boundaries.
Deployment Options
| Path | What | Guide |
|---|---|---|
| Local | Docker on your machine, vault bind-mounted | deploy/local/ |
| Remote | VPS + Obsidian Sync, access from anywhere | deploy/remote/ |
| AWS (SST) | Full IaC: Lightsail + API Gateway + Lambda + CI/CD | DEPLOY.md |
Development
# Run locally with hot reload
PUBLIC_URL=http://localhost:8000 MCP_AUTH_TOKEN=local-dev-token VAULT_PATH=~/Vault npm run dev:mcp
# Tests
npm test
# Full check suite
npm run prettier:check && npm run lint && npm test && npm run build
MCP Inspector — interactive browser UI for testing tools:
# Start server (terminal 1), then:
npx @modelcontextprotocol/inspector
# Enter http://localhost:8000/mcp as URL, local-dev-token as Bearer token
See CONTRIBUTING.md for the full development setup.
Tips
For Claude users
The obsidian-vault skill teaches Claude how to write Obsidian-compatible content — frontmatter, wikilinks, tags, callouts, and plugin-specific syntax. vault-cortex delivers the content; obsidian-vault ensures it renders correctly in Obsidian. Available for Claude Code and Claude Desktop.
Acknowledgments
vault-cortex's remote capability exists because of @Belphemur's obsidian-headless-sync-docker — a headless Obsidian Sync client that runs in Docker without a display server. It's the piece that makes "access your vault from anywhere" possible.
Contributing
See CONTRIBUTING.md for development setup, code conventions, and PR guidelines.
License
MIT
Security
Report vulnerabilities privately — see SECURITY.md.
