Obsidian Vault MCP

HTTP Model Context Protocol server that gives AI agents controlled access to a local Obsidian vault.

Built for agent runtimes (Grok bots, Claude, OpenClaw, custom MCP clients) that need to list, read, search, create, update, rename, and carefully delete markdown notes.

Features

• Streamable HTTP MCP endpoint (/mcp)
• Bearer / API-key auth
• Full-vault mode (ALLOWLIST=*) or folder allowlists
• Read tools: list_notes, list_folder, read_note, search_notes
• Write tools: create_note, append_note, update_note, create_folder, rename_path, delete_path
• Blocks .obsidian, .git, dotfiles, .env, and key material
• Atomic writes + size limits
• Health endpoint for ops: /healthz

Quick start

npm install
export VAULT_ROOT="/absolute/path/to/your/vault"
export BEARER_TOKEN="$(openssl rand -hex 32)"
export ALLOWLIST="*"
export WRITE_ALLOWLIST="*"
export MODE="read-write"
export PORT=8790
export BIND=127.0.0.1
export PUBLIC_BASE="http://127.0.0.1:8790"
npm start

Health check:

curl -s http://127.0.0.1:8790/healthz | jq .

Environment variables

Variable	Required	Default	Description
VAULT_ROOT	yes	—	Absolute path to the Obsidian vault
BEARER_TOKEN	yes	—	Shared secret for MCP clients
ALLOWLIST	no	sample folders	Comma list of relative folders, or * for whole vault
WRITE_ALLOWLIST	no	same as ALLOWLIST	Write scope; * = whole vault (still blocks secrets/dotfiles)
MODE	no	read-write	read-write or read-only
PORT	no	8790	Listen port
BIND	no	127.0.0.1	Bind address
PUBLIC_BASE	no	http://127.0.0.1:8790	Public base URL advertised in metadata
MAX_SEARCH_HITS	no	25	Search result cap
MAX_FILE_BYTES	no	400000	Max note size for reads
MAX_WRITE_BYTES	no	350000	Max note size for writes

Auth headers accepted:

• Authorization: Bearer <token>
• X-Api-Key: <token>
• X-Obsidian-Token: <token>

MCP tools

Read

• list_notes — list markdown paths (optional prefix)
• list_folder — list files/dirs (recursive optional)
• read_note — read one note + simple frontmatter
• search_notes — case-insensitive substring search

Write (when MODE=read-write)

• create_note — create markdown note (overwrite optional)
• append_note — append to note
• update_note — replace full note
• create_folder — create folder tree
• rename_path — rename/move file or folder
• delete_path — delete markdown file or folder (recursive for non-empty)

Safety:

• never serves .obsidian, .git, hidden paths, .env, or key files
• write limited to .md / .markdown / .txt
• protected top-level structure anchors cannot be deleted wholesale
• no secrets belong in the vault or this server config committed to git

Reverse proxy example (nginx)

location ^~ /obsidian-mcp/ {
  proxy_pass http://127.0.0.1:8790/;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header Authorization $http_authorization;
  proxy_set_header X-Api-Key $http_x_api_key;
  proxy_buffering off;
}

Expose only over HTTPS and keep BIND=127.0.0.1 on the Node process.

Grok / agent prompt snippet

You have MCP tools for an Obsidian vault via obsidian-vault-mcp.

Rules:
1. First call list_folder path="" to see top-level structure.
2. Read OBSIDIAN-STRUCTURE.md if present before reorganizing.
3. Prefer append_note for changelogs; do not rewrite history casually.
4. Create notes only as .md under clear topic folders.
5. Never store secrets, tokens, private keys, or .env values.
6. Use search_notes before creating near-duplicate docs.
7. Use rename_path to organize; use delete_path only for clearly obsolete drafts.

Security notes

• This server is powerful. Treat BEARER_TOKEN like a password.
• Prefer network isolation + reverse proxy auth in production.
• Full-vault write mode is intentional for trusted internal agents; tighten WRITE_ALLOWLIST for less-trusted bots.
• Do not commit .env, tokens, or real vault contents.

License

MIT