Vault Cortex

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 .md files 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

Related MCP server: Vault MCP Server (mschuchard)

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)

Configuration

All settings are environment variables with sensible defaults.

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):

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

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.