obsidian-vault-mcp

<p align="center"> <img src="./assets/header.svg" alt="obsidian-icloud-mcp — an Obsidian MCP that survives iCloud eviction" width="100%"> </p>

<p align="center"> <a href="https://github.com/QEbellavita/obsidian-icloud-mcp/actions/workflows/test.yml"><img src="https://github.com/QEbellavita/obsidian-icloud-mcp/actions/workflows/test.yml/badge.svg" alt="tests"></a> <a href="https://doi.org/10.5281/zenodo.21485168"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.21485168.svg" alt="DOI"></a> </p>

An MCP server for Obsidian vaults that doesn't hang on iCloud.

Read, search, create and update notes from your assistant — and see exactly how much of the vault iCloud has actually left on disk. Seven tools, no daemon, no index to rebuild.

Why another one

Because the obvious implementation breaks on iCloud Drive, and breaks in the worst possible way: it hangs forever.

If your vault lives in iCloud with Optimize Mac Storage on, macOS evicts note bodies and leaves dataless placeholders behind. They look like ordinary files — stat reports a real size — but the first read() blocks while macOS fetches the content over the network. On an evicted vault, a naive search hits hundreds of those in a row and never returns. No error, no timeout, just a search that never finishes.

A deadline alone doesn't fix it: a single blocking read never yields control back, so the between-files clock check is never reached. The only reliable signal is stat's block count — a dataless placeholder reports blocks == 0 despite a non-zero size.

This server checks that before every read, and bounds total search time on top. Evicted notes are skipped and reported, not waited on:

{
  "matches": [ ... ],
  "scanned": 112,
  "total": 486,
  "unavailable": 43,
  "incomplete": true,
  "note": "Searched 112/486 notes; 43 are not downloaded from iCloud yet and were skipped. Results may be incomplete."
}

incomplete: true means "there may be more" — rather than silently returning partial results as if they were the whole answer. The counts distinguish the two reasons: notes that weren't materialised (unavailable) versus hitting the time budget.

Reading one specific evicted note fails honestly with "not downloaded from iCloud" instead of blocking.

<p align="center"><img src="./assets/demo.gif" alt="Animated demo — a search reports 5 of 8 notes scanned with 3 iCloud-evicted notes skipped and flagged, then vault_health shows materialized vs evicted counts and points at obsidian_warm_notes" width="90%"></p>

Install

Point your MCP client at it:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-icloud-mcp"],
      "env": {
        "OBSIDIAN_VAULTS": "{\"Personal\":\"/Users/you/Documents/Notes\"}"
      }
    }
  }
}

Or from source: git clone https://github.com/QEbellavita/obsidian-icloud-mcp and point command: node, args: [/absolute/path/to/obsidian-icloud-mcp/server.js] at the checkout.

Formerly named obsidian-vault-mcp; renamed because that npm name belongs to an unrelated project by another author — npx obsidian-vault-mcp is not this server. The old GitHub URL redirects here.

OBSIDIAN_VAULTS is a JSON object of name → absolute path. Multiple vaults are fine:

"OBSIDIAN_VAULTS": "{\"Personal\":\"/Users/you/Notes\",\"Work\":\"/Users/you/Work/vault\"}"

With no vaults configured the server starts and advertises zero tools, rather than crashing in a way your host reports as a broken server.

Tools

Tool
obsidian_list_notes	List Markdown notes, optionally under a subdirectory
obsidian_search_notes	Full-text search with path, line number and excerpt
obsidian_read_note	Read one note
obsidian_create_note	Create a note; refuses to overwrite
obsidian_update_note	Atomic overwrite of an existing note
obsidian_vault_health	Materialized vs evicted counts, bytes pending, largest evicted notes — stat-only, never blocks
obsidian_warm_notes	Opt-in background downloads for evicted notes, bounded per call

Safety

The vault boundary is enforced, not assumed:

• Paths must be relative and stay inside the configured vault — ../ is rejected
• Symlinks that resolve outside the vault are rejected, not followed
• Only .md files are read or written
• create refuses to clobber; update refuses to create
• Writes are atomic (temp file + rename), so an interrupted write can't truncate a note

Directory walking skips anything that can't hold notes — .git, node_modules, .obsidian — which also stops a vault that happens to be a source checkout from taking minutes to list. And it never descends into a stalling bundle directory, where even readdir can block indefinitely on iCloud.

Tests

npm test

23 tests. Nineteen cover the service directly — including every iCloud failure mode above, driven through an injected fs so eviction is simulated deterministically rather than depending on your actual sync state. Four drive the real server over a real stdio transport.

Citing

If this server is useful in your workflow, cite it via the repo's CITATION.cff (GitHub's "Cite this repository" button), or the Zenodo DOI, 10.5281/zenodo.21485168 — a concept DOI that always resolves to the latest archived version.

Licence

MIT — see LICENSE.