Back to Browse
Free
Server data from the Official MCP Registry
MCP server for Obsidian vaults — search, memory, link graph, 23 tools, OAuth-protected.
About
MCP server for Obsidian vaults — search, memory, link graph, 23 tools, OAuth-protected.
Security Report
10.0
Low Risk10.0Low RiskValid MCP server (1 strong, 1 medium validity signals). 1 code issue detected. No known CVEs in dependencies. Imported from the Official MCP Registry. 1 finding(s) downgraded by scanner intelligence.
5 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Bearer token for MCP client authentication. Must match the Authorization header sent by clients. Generate with: openssl rand -hex 32Required
Environment variable: MCP_AUTH_TOKEN
Public URL clients use to reach this server. Used as the OAuth issuer URL in discovery metadata. Override when exposing the server outside localhost or on a non-default port.
Environment variable: PUBLIC_URL
Vault folder for structured memory files (About Me-style notes).
Environment variable: MEMORY_DIR
IANA timezone for timestamps and daily note resolution.
Environment variable: TZ
Logging verbosity.
Environment variable: LOG_LEVEL
Directory for persistent log files. Unset by default — logs go to stdout only. Set to /data/logs to also write date-stamped .log files to the persistent volume.
Environment variable: LOG_DIR
Days to retain persistent log files before cleanup.
Environment variable: LOG_RETENTION_DAYS
Comma-separated vault folder names blocked from vault_delete_note. Default: MEMORY_DIR and "Daily Notes".
Environment variable: PROTECTED_PATHS
Comma-separated vault folder names excluded from vault_find_orphans. Default: "Daily Notes", "Templates", MEMORY_DIR.
Environment variable: ORPHAN_EXCLUDE_FOLDERS
Override the OAuth service documentation URL exposed via discovery metadata.
Environment variable: SERVICE_DOCUMENTATION_URL
Documentation
View on GitHubFrom the project's GitHub README.
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.
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.
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
Security
Report vulnerabilities privately — see SECURITY.md.
Reviews
No reviews yet
Be the first to review this server!
More Security MCP Servers
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
137
Stars
464
Installs
8.0
Security
4.8
Local
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
-
Stars
61
Installs
10.0
Security
5.0
Local
MarkItDown
Freeby Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
120.0K
Stars
19
Installs
6.0
Security
5.0
Local