← Back to directory
V

Vault Cortex MCP Server

Community
Standalone MCP server for Obsidian vaults: hybrid search, notes & files, structured memory, tasks, OAuth 2.1.
GitHub source repository ↗
★ 15 Stars Category · Filesystem Popular
79FMRS · B

Vault Cortex is a feature-complete, well-engineered third-party MCP server for Obsidian: hybrid search (FTS5 + vectors + reranking, all local), entry-granular structured memory, Kanban-aware tasks, attachment file reading, and full OAuth 2.1 with data-integrity safeguards — rare depth in this category. It is not official (the author is not the Obsidian team), but it is MIT-licensed, easy to deploy in one Docker container, and ships a CLI wizard. Best suited to serious Obsidian users comfortable with self-hosting.

Reliability
12/20
Security and permissions
18/20
Maintenance
15/20
Documentation
19/20
Setup experience
15/20
Read the FMRS scoring method →

Vault Cortex is a standalone MCP server that gives any AI agent hybrid search, task management, structured memory, and read/write access to an Obsidian vault. No plugins and no running Obsidian required: one Docker container works directly with the .md files on disk. Deploy on a VPS with Obsidian Sync to access the same vault from a phone, claude.ai, or any remote MCP client, secured with OAuth 2.1. Search combines FTS5 keyword matching and vector semantic similarity via RRF fusion, refined by a cross-encoder reranker. The memory layer holds dated, append-only entries; the task layer parses both Tasks plugin emoji and Dataview inline-field formats with Kanban lane awareness; file tools read images, canvases, PDFs, and other non-markdown files. Transport is streamable-http (http://localhost:8000/mcp or <PUBLIC_URL>/mcp).

Tools

vault_read_note
Read a note — full body, properties, outline, or a section
vault_write_note
Create a note (fails if it exists; set overwrite to replace)
vault_patch_note
Heading-targeted edit (append, prepend, replace, insert)
vault_replace_in_note
Find-and-replace text in a note
vault_delete_span
Delete a block of lines by short anchors, no full re-quote
vault_list_notes
List notes with optional glob/folder filter
vault_delete_note
Delete a note (protected paths enforced)
vault_move_note
Move or rename a note, rewriting links across the vault
vault_search
Hybrid search with tag/folder/property/date 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
vault_list_tasks
Vault-wide task index — Kanban-aware, 6 date fields, priority, folder/heading scope
vault_update_task
One-call status, priority, and lane changes — auto-detects done lanes on Kanban boards
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, their sections, and each file's entry policy
vault_memory_recall
Entry-granular hybrid recall of a topic across memory files, oldest-first
vault_list_property_keys
All property keys with sample values
vault_list_property_values
Distinct values for a property key
vault_search_by_property
Find notes by property key-value
vault_update_properties
Add or update properties without touching the body
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
vault_read_file
Read a non-markdown file — images delivered as images, canvases as readable outlines
vault_list_files
Browse the vault's non-markdown files with sizes and per-extension counts
vault_get_daily_note
Today's (or any date's) daily note

Setup

Requires Docker (or Podman, OrbStack, etc.); the CLI needs Node.js >= 20.12. Local: run npx vault-cortex@latest init — the wizard picks your vault path, generates the auth token and config, starts the server, and prints the URL (http://localhost:8000/mcp). Remote: on a VPS run npx vault-cortex@latest init --mode remote with an Obsidian Sync subscription. Manual docker compose setup is also available (image ghcr.io/aliasunder/vault-cortex). Connect Claude Code: claude mcp add --scope user --transport http vault-cortex http://localhost:8000/mcp.

Fit and risk

Best for

  • Serious Obsidian users who want AI agents reading and writing their vault
  • Users wanting self-hosted, plugin-free operation with no external APIs
  • Mobile/multi-device workflows accessing the vault remotely
  • Security-conscious users (OAuth 2.1, atomic writes, container hardening)

Not for

  • Users unwilling to run Docker or self-host a server
  • Non-Obsidian note tools (Notion, Logseq, etc.)
  • Scenarios requiring only a stdio local process without an HTTP server
  • Remote multi-device sync without an Obsidian Sync subscription (the remote image requires one)

Required permissions

  • Read/write access to the Obsidian vault folder (bind mount /vault, rw)
  • Persistent /data volume (search index, OAuth token DB, logs)
  • MCP_AUTH_TOKEN as Bearer token (also the JWT signing key)
  • Obsidian Sync token for headless sync in remote mode
  • Local download of embedding/reranker models (~45MB total), no external API calls

Risks and side effects

  • The server can read and write personal notes — guard MCP_AUTH_TOKEN carefully; leaking it exposes the whole vault
  • Writes to real note files; despite atomic writes and protected paths, misconfiguration can alter data
  • OAuth token DB lives on the /data volume; container compromise could expose valid sessions
  • Remote deployments expose a public port — set PUBLIC_URL and reverse proxy correctly
  • The remote image bundles proprietary obsidian-headless (not MIT-licensed); requires an active Obsidian Sync subscription

Troubleshooting

  1. 401 errors: confirm the client Authorization header matches the container's MCP_AUTH_TOKEN
  2. File changes not indexed on Windows: set WINDOWS_MODE=true to enable polling
  3. claude.ai cannot reach localhost: its connectors only work with a remote (https) deployment
  4. Claude Desktop local connection: register via the mcp-remote stdio bridge in claude_desktop_config.
  5. No semantic matches in search: verify EMBEDDING_ENABLED is true
  6. Memory or model-download issues: semantic search needs ~2GiB RAM, or set EMBEDDING_ENABLED=false to fall back to FTS5

Use cases

Search and recall personal knowledge base content from a phone or remote client
Have an agent read session logs, synthesize lessons, and write them back to the vault
Vault-wide task triage: query by status, dates, priority; complete or reprioritize in one call
Maintain a dated, evolving memory layer of preferences and principles
Analyze the link graph and find orphaned notes
Let agents read screenshots, diagram PDFs, canvases, and other attachments

Supported clients

Claude CodeFull support
Claude DesktopFull support
claude.aiPartial support
CursorPartial support
OpenCodeFull support
MCP InspectorFull support