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

Related MCP server: obsidian-autom8

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

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