Set up a Vault Cortex MCP server for your Obsidian vault in one command:
npx vault-cortex@latest initVault Cortex is a standalone, remote-capable MCP server that gives any AI agent hybrid search, task management, structured memory, and read/write access to your Obsidian vault — including its images, PDFs, canvases, and data files — see the full feature overview. The server runs as a Docker container; this CLI scaffolds the config and manages the container so you don't have to.
init— interactive setup: scaffold the config, generate the auth token, start the serverconfigure— change optional settings interactively and restart to apply themupgrade— pull the latest image and re-create the container; your data staysstart— start the server with your saved settings, e.g. afterdownrestart— re-create the container so your.envedits take effect; no image pulllogs— show the server's logs, live or after the factdown— stop and remove the container; your data staysget-sync-token— generate an Obsidian Sync auth token for remote setups
Run npx vault-cortex@latest <command> --help for all flags.
npx vault-cortex@latest initWhat it does:
- Asks how you want to run it:
- Local — Docker on this machine, your vault folder bind-mounted
- Remote — a VPS with Obsidian Sync, reachable from any device
- Offers the most common optional settings — memory layer and folder, daily notes folder and format, file tools, read-only mode, semantic search, port, timezone (plus sync direction for remote) — press enter to keep the defaults, or pick the ones you want to change
- Generates a
.envfile with a securely generatedMCP_AUTH_TOKEN - Optionally starts the container and waits for the health check
- Prints your connection details — the MCP URL, your auth token, and how to connect your client
Re-running init where a setup already exists asks first — declining leaves
everything unchanged and points you at configure, the right
tool for changing settings in place. Existing files are never overwritten
without asking. During a remote setup, init offers to generate your
Obsidian Sync token as part of the flow.
Flags:
--mode local|remote— skip the mode prompt--vault-path <path>— absolute path to your vault (local mode)--dir <path>— directory to write config files into (default./vault-cortex)--yes— non-interactive local setup with defaults; requires--vault-path
Non-interactive example:
npx vault-cortex@latest init --yes --vault-path /path/to/YourVaultChange optional settings on an existing setup:
npx vault-cortex@latest configureShows the same settings chooser as init, pre-filled with your
current values, saves your picks to .env, and offers to restart the
container so they take effect.
Settings not in the chooser live in .env too: edit the value there, then
run restart. That's also how you clear a daily notes setting
back to your vault's own configuration — comment out or delete its line.
Use --dir <path> if your config isn't in ./vault-cortex.
Pull the latest image, re-create the container, and verify health:
npx vault-cortex@latest upgradeRun it from the same directory where you ran init — it looks for your
config in ./vault-cortex/.env (pass --dir <path> if you scaffolded
somewhere else).
Safe by design:
- Your vault data, search index, and
.envsettings are preserved across upgrades — only the server image is replaced. - Any edits you've made to
.envare applied on the way up (docker restartalone does not re-read env files).
Prefer Docker Compose? The CLI uses docker run for simplicity, but the
deploy guides
include Compose files you can use directly. If you set up with Compose, stick
with Compose for updates too (docker compose pull && docker compose up -d)
— the CLI and Compose manage the container independently.
Start the server with your saved settings and verify health:
npx vault-cortex@latest startThis is the command the CLI's own guidance points to whenever the server
isn't running — after down, or an init where the server wasn't
started. It's the same cycle as restart under the name you'd
look for: any existing container is replaced, and Docker pulls the server
image automatically on a first start.
Use --dir <path> if your config isn't in ./vault-cortex.
Re-create the container from your .env and verify health:
npx vault-cortex@latest restartUse it after editing .env — settings are only read when the container is
created, so a plain docker restart won't pick them up, but this will. Unlike
upgrade, it never updates the server image: you get the same
version back, with your current settings applied.
Use --dir <path> if your config isn't in ./vault-cortex.
Show the server's logs:
npx vault-cortex@latest logsFlags:
--follow— keep streaming new output until you press ctrl-C--since <time>— only logs newer than this (e.g.10m,2h, or a timestamp)--dir <path>— directory containing.env(default./vault-cortex)
npx vault-cortex@latest logs --follow --since 10mStop and remove the container:
npx vault-cortex@latest downSafe by design: your vault, search index, and .env settings all live
outside the container, so nothing is lost. Start again any time with
start. Running down when nothing is running is fine — it
just tells you there's nothing to stop.
Use --dir <path> if your config isn't in ./vault-cortex.
Generate an Obsidian Sync auth token — needed for remote setups — without leaving the CLI:
npx vault-cortex@latest get-sync-tokenThe command prompts for your Obsidian account email, password, and MFA code
(if enabled), signs in via the Obsidian API, and prints the token. Use
--dir <path> to write the token straight into an existing .env instead:
npx vault-cortex@latest get-sync-token --dir ./vault-cortexDuring init --mode remote, this flow is offered automatically.
- Node.js >= 22.12 (only for this CLI — the server itself runs in Docker)
- Docker or a Docker-compatible
runtime (e.g. OrbStack, Colima, Podman) to run the server — the CLI
manages the container through the
dockercommand (on Linux, see Docker Engine)