Which integrations are available for this server?

Provides full access to an Obsidian vault, allowing AI agents to search, read, write, manage structured memory, query backlinks, and work with daily notes.

vault-cortex by aliasunder

Gitleaks GitHub Release License: MIT Node.js TypeScript MCP Server 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 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

Phase	What	Status
1	Vault CRUD, full-text search (FTS5), memory layer, OAuth 2.1	Complete
2	Semantic search + knowledge graph via LightRAG	Planned

Related MCP server: Obsidian

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.

vault-cortex