MCP 服务器

obsidian-vault-mcp

An MCP server for Obsidian vaults that handles iCloud eviction gracefully, allowing reading, searching, creating, and updating notes without hanging.

README

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

Read, search, create and update notes from your assistant. Five 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.

Install

Clone it, then point your MCP client at server.js:

git clone https://github.com/QEbellavita/obsidian-vault-mcp

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-vault-mcp/server.js"],
      "env": {
        "OBSIDIAN_VAULTS": "{\"Personal\":\"/Users/you/Documents/Notes\"}"
      }
    }
  }
}

Not on npm. The name obsidian-vault-mcp on the npm registry is an unrelated project by another author — don't npx it expecting this server.

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

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

15 tests. Eleven 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.