Obsidian MCP Server

A remote MCP server that exposes a folder of Markdown notes — an Obsidian vault, or just a plain folder of .md files — to LLM clients like Claude and ChatGPT. It talks Streamable HTTP, operates directly on the filesystem, and has no dependency on the Obsidian app itself.

MCP client --HTTP--> server.mjs (127.0.0.1:MCP_PORT) --node:fs--> VAULT_ROOT

The server only binds to 127.0.0.1. It does not do TLS termination, authentication, or expose itself to the network — that's a separate concern, left to whatever you put in front of it (see Exposing it remotely).

What it can do

Most of the metadata tools (query_notes, list_tags, list_tasks, get_backlinks) ride on one internal vault index that walks the vault once and caches parsed frontmatter/tags/headings/links/tasks per file, keyed by (path, mtime), so repeat calls only re-parse notes that actually changed.

Related MCP server: Obsidian MCP Server

Write model

• New notes can only be created inside Inbox/ (configurable). The one exception is obsidian_append_daily_note, which may create today's daily note outside Inbox/ because that path is fully deterministic and the write is append-only.

• Editing, moving/renaming, and deleting existing notes is allowed anywhere in the vault.

• Delete is soft: obsidian_delete_note moves the file into .trash/ instead of unlinking it, so it's always recoverable by hand. .trash/ is excluded from every listing/search tool.

• Move is wikilink-safe: obsidian_move_note rewrites every other note's [[wikilink]]/![[embed]] that resolves to the moved note (bare filename if that's still unique, otherwise the full path), preserving aliases and #heading anchors.

• Path safety: every tool resolves paths through one canonical helper that rejects absolute paths, .. traversal, and symlinks pointing outside VAULT_ROOT.

• Writes are atomic: temp file + rename in the same directory, so a client watching the folder (Obsidian, a sync client) never sees a partial write.

Configuration

Copy .env.example to .env and fill in:

Running it

npm install
cp .env.example .env   # set VAULT_ROOT
node server.mjs

curl -s http://127.0.0.1:3001/health   # {"ok":true}

That's the whole server: one Node process, no database, no build step. npm run start does the same thing.

Exposing it remotely

Claude web/mobile and ChatGPT connect to MCP servers over the network, not over stdio like Claude Desktop — so using this from those clients means putting a real HTTPS URL with authentication in front of 127.0.0.1:MCP_PORT. This server has no authentication of its own; that's intentionally left to whatever sits in front of it. /mcp should be behind that auth layer; /health is safe to leave open, it returns nothing but {"ok":true}.

Once the client can reach the URL, add it as a custom connector (Claude) or a developer-mode connector (ChatGPT — standard ChatGPT connectors only invoke tools literally named search/fetch and won't show any actions here, since this server intentionally doesn't add those aliases).

A note on cloud-synced vaults

If VAULT_ROOT lives on a cloud-synced drive (iCloud Drive, Dropbox, OneDrive, etc.), a file can be an evicted placeholder that isn't actually on disk yet. readFileSync on one either blocks while it downloads or errors. The search/read tools handle this per-file — an unreadable note is reported individually rather than failing the whole call — but if it becomes a real problem, opening the file once in the desktop app (or your sync client's "keep local copy" option) forces it to materialize.

Development

The server is split into server.mjs (tool registration + Streamable HTTP transport) and lib/:

• lib/config.mjs — env loading and validated config constants

• lib/vault-fs.mjs — resolveInVault, atomic writes, vault walking, ignore rules

• lib/markdown.mjs — frontmatter/heading/task/wikilink/tag parsing (fence-aware)

• lib/vault-index.mjs — the cached vault-wide index and link resolution/backlink graph

• lib/daily-notes.mjs — reads .obsidian/daily-notes.json, Moment-token date formatting

• lib/capture.mjs — the obsidian_capture_inbox payload normalizer and Markdown renderer

scripts/smoke-test.mjs drives the MCP surface end-to-end (initialize → tools/list → tools/call) against a scratch vault, without needing a real client:

VAULT_ROOT=/tmp/fake-vault node server.mjs &
node scripts/smoke-test.mjs

It exercises every tool above, including path-traversal rejection, wikilink rewriting on move, and dangling-backlink reporting on delete.

License

MIT — see LICENSE.