👁 CI
👁 Gitleaks
👁 Trivy
👁 GitHub Release
👁 License: MIT
👁 Node.js
👁 TypeScript

👁 vault-cortex MCP server

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 and 3 guided prompts 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

• Guided workflows — three built-in prompts that orient a new session to your vault's conventions, review your memory layer as a timeline, or reconcile a day's work — assembled from live vault content each time you run them

Roadmap

Related MCP server: Vault MCP Server (mschuchard)

Quick Start

Local (2 minutes — Docker + your vault folder)

Prerequisites: Docker, Node.js >= 20.12 (only for the CLI — the server itself runs in Docker), and an Obsidian vault (or any folder of .md files).

npx vault-cortex@latest init

That's it — the CLI asks for your vault path, generates the auth token and config files, starts the server, and prints the connection details for your MCP client.

# 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

Full local guide →

Remote (access from anywhere — Docker + Obsidian Sync)

Prerequisites: a VPS with Docker, an Obsidian Sync subscription, and Node.js >= 20.12 (only for the CLI — the server itself runs in Docker).

# On your VPS:
npx vault-cortex@latest init --mode remote

That's it — the CLI walks through the public URL, Obsidian Sync token (it can run the token generator for you), and auth config, then starts the server.

# 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

Full remote guide →

Connect your MCP client

Add the server URL in any MCP client — Claude Code, Claude Desktop, Cursor, OpenCode, or any other. OAuth clients open a consent page in your browser — approve with your token, and the client handles token renewal from then on. Clients without OAuth (MCP Inspector, scripts) send the token directly as an Authorization: Bearer header.

Claude Code:

claude mcp add --scope user --transport http vault-cortex http://localhost:8000/mcp # local (or <PUBLIC_URL>/mcp)

--scope user registers the server for every project; omit it to scope it to the current directory only.

Claude Desktop: the "Add custom connector" dialog only accepts https URLs. With an https PUBLIC_URL, add it directly in the connector dialog; for a localhost server, register it in claude_desktop_config.json through the mcp-remote stdio bridge instead:

{
 "mcpServers": {
 "vault-cortex": {
 "command": "npx",
 "args": [
 "-y",
 "mcp-remote",
 "http://localhost:8000/mcp",
 "--header",
 "Authorization: Bearer <your MCP_AUTH_TOKEN>"
 ]
 }
 }
}

claude.ai (web and mobile) connects to the remote setup only — its connectors are fetched server-side and can never reach localhost.

"Remote MCP server" refers to the connection type (HTTP) — in the local setup the server still runs entirely on your machine.

See Authentication for both methods and token lifetimes.

Tools (23)

Prompts (3)

Tools are model-driven — the assistant calls them. Prompts are workflows you trigger: run one to instantly ground a session in your vault's structure, reflect on how your preferences have evolved, or reconcile a day's work into follow-ups and memory. Each prompt assembles live vault content when you invoke it, so the context is always current.

Prompts adapt to your configuration (MEMORY_DIR, daily-notes settings) and work for any vault out of the box. Pass max_chars to cap embedded content if your client has payload limits.

Client support: Prompts work in Claude Desktop (Chat and Cowork — via the + menu under your connector), Claude Code (slash commands), and OpenCode. Support in other clients (Cursor, Windsurf) varies — see the MCP clients matrix for the latest.

Properties

Vault Cortex indexes every property in your notes, but five get promoted treatment — dedicated columns for fast filtering, and top-level fields in every search and discovery result:

All other properties are still fully queryable — use vault_search with filters.properties for combined text + metadata queries, or vault_search_by_property for metadata-only lookups. vault_list_property_keys and vault_list_property_values discover what properties exist across your vault.

These are conventions, not requirements — Vault Cortex works with any property schema. Promoted properties just give you richer filtering and cleaner results out of the box.

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.

Companion: obsidian-vault skill

The MCP server works on its own with any client. For agents that support skills (Claude Code, Cursor, Windsurf, Cline, and 70+ others), the obsidian-vault skill adds deeper knowledge of Obsidian-flavored markdown — frontmatter conventions, callout syntax, and plugin-specific formats like Dataview, Tasks, and Kanban.

npx skills add aliasunder/agent-skills --skill obsidian-vault

Skill source →

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. The remote stack runs a small fork that adds a build-time config chown and --device-name on the initial Sync registration (upstream PR #8 remains open).

Contributing

See CONTRIBUTING.md for development setup, code conventions, and PR guidelines.

License

MIT

Security

Report vulnerabilities privately — see SECURITY.md.

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• vault_delete_memoryA
• vault_delete_noteA
• vault_find_orphansA
• vault_get_backlinksA
• vault_get_daily_noteA
• vault_get_memoryA
• vault_get_outgoing_linksA
• vault_list_memory_filesA