seekstone

# Seekstone

> Seekstone is an Obsidian MCP server that connects Claude (and any Model Context Protocol client) to your Obsidian vault. It reads the vault directly from disk — no Obsidian app, no Local REST API plugin, no network calls at runtime. Works on macOS, Linux, and Windows.

Website: https://seekstone.dev

Seekstone is published to npm as `seekstone`. (It was previously also published as `obsidian-mcp-seekstone`; that alias is deprecated — existing installs keep working but it no longer receives updates.)

## One-prompt install for agents

A user can paste this prompt into any coding agent (Claude Code, Cursor, Windsurf) and the agent can install seekstone unattended:

> Install the **seekstone** MCP server for this editor. Run `npx -y seekstone init --client code --write` (use `desktop`, `cursor`, or `vscode` for other clients). It auto-detects my Obsidian vault; if it lists several, ask me which one and re-run with `--vault "<path>"`. Relay any errors to me, then tell me to restart this session so the seekstone tools load.

`seekstone init` is fully non-interactive: `--write` applies the config (Claude Code via `claude mcp add`, other clients via an additive JSON patch with a timestamped backup); without `--write` it only prints the config. Exit code 0 on success, 1 with a `✗`-prefixed reason on failure. An unknown `--client` value is an error, not a silent fallback.

## Why filesystem-direct?

Most Obsidian MCP servers return full note content for every search hit. Benchmarked across committed 1,000/5,000/10,000-note synthetic vaults against 7 other servers (open-source harness, reproducible): Seekstone returns ~2 KB per search and stays flat as the vault grows, while REST-proxy servers grow with the vault — up to 95 MB per query at 10k notes, and a single broad query averaged 370.9 MB / ~97.8M tokens per call. That is up to a ~47,000× context-tax reduction. Warm keyword-search latency is 5.2 ms at 10k notes (the shipped semantic pipeline ~26 ms) — the fastest alternative measured is ~7× slower, the REST-proxy generation ~110–300× slower. Full results: https://seekstone.dev/benchmarks

## How to install (Claude Desktop)

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "seekstone": {
      "command": "npx",
      "args": ["-y", "seekstone"],
      "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}
```

## How to install (Claude Code)

```bash
claude mcp add seekstone --env SEEKSTONE_VAULT=/absolute/path/to/your/vault -- npx -y seekstone
```

## How to install (Cursor)

```bash
npx -y seekstone init --client cursor --write
```

Or add the same `mcpServers` JSON block as Claude Desktop to `~/.cursor/mcp.json`. Any other MCP-over-stdio client (VS Code/Copilot, Windsurf, Cline, Continue, JetBrains, Zed) takes the identical block in its own MCP config file.

## Tools (21)

Read:
- `search` — full-text search returning ranked excerpts, ~120 chars by default and tunable (not full notes); optional `mode: "semantic"`/`"hybrid"` for meaning-based search via a local embedding model (`SEEKSTONE_SEMANTIC=1` + one-time `npx -y seekstone fetch-model`; fully offline at runtime)
- `query_notes` — structured metadata query: filter notes by frontmatter key/value predicates, tag, folder, modified time, and size; returns compact rows (path + title by default), not note content
- `context_pack` — answer-ready context for a natural-language question in one call, hard-capped at a byte budget (default 2048): ranked excerpts, linked neighbor notes with one-line summaries, and follow-up source paths
- `read_note` — read the full content of a note by vault-relative path; supports section, block, or line-range slices
- `list_notes` — list notes filtered by folder prefix or tag
- `list_tags` — list all tags sorted by usage count or alphabetically
- `outline_note` — a note's heading and block structure without its full content
- `get_backlinks` — all notes linking to a given note
- `get_links` — all outgoing wikilinks and markdown links from a note
- `get_periodic_note` — read a daily/weekly/monthly/quarterly/yearly note, path resolved from vault config
- `list_writes` — recent journaled writes (seq, timestamp, tool, paths, undoable); metadata only, never note content

Write:
- `create_note` — create a note with optional frontmatter and body
- `delete_note` — move a note to the vault's `.trash/` folder (recoverable, Obsidian-compatible); `permanent: true` skips the trash — the write journal still lets `undo_write` restore it
- `move_note` — move or rename a note, rewriting wikilinks and markdown links in other notes that point at it (link-aware; `rewriteLinks: false` to opt out)
- `rename_heading` — rename a heading in a note, rewriting every `[[note#heading]]` wikilink and embed across the vault (aliases preserved, fenced code blocks untouched)
- `append_note` — append text to a note body without touching frontmatter
- `patch_frontmatter` — set, update, or delete frontmatter keys while preserving key order and quote style
- `patch_note` — append, prepend, or replace text at a heading or block reference (`createIfMissing` to add the section)
- `replace_in_note` — find and replace text in the note body (literal or regex, whole-word, case sensitivity, optional limit — replaces all occurrences by default, dry-run preview)
- `append_periodic_note` — append to today's periodic note, creating it from a template if needed
- `undo_write` — revert a journaled write byte-for-byte (multi-file moves/renames restored whole, deletes restored even if permanent); refuses with `undo_conflict` if the file changed since unless `force: true`; the undo is itself journaled, so `undo_write({ seq })` on an undo entry redoes it

## Requirements

- Node.js ≥ 22
- No Obsidian app or plugins required
- Semantic/hybrid search additionally needs `SEEKSTONE_SEMANTIC=1` and a one-time `npx -y seekstone fetch-model` (~30 MB, SHA-256-verified; the running server never fetches)

## Environment variables

- `SEEKSTONE_VAULT` (required) — absolute path to the vault
- `SEEKSTONE_READ_ONLY=1` — unregister and reject all 10 write tools
- `SEEKSTONE_WRITE_PATHS` — comma-separated globs restricting where writes may land
- `SEEKSTONE_SEMANTIC=1` — enable semantic/hybrid search modes (model must be fetched first)
- `SEEKSTONE_MODEL_PATH` — override the embedding-model directory
- `SEEKSTONE_CACHE_DIR` — cache root for the model and per-vault embedding caches (default `~/.cache/seekstone`)
- `SEEKSTONE_LOG_LEVEL` — error | warn | info (default) | debug
- `SEEKSTONE_LOG_FILE` — append JSON-line logs at this absolute path
- `SEEKSTONE_LOG_MAX_SIZE` — log-rotation threshold (default 5 MB)
- `SEEKSTONE_AUDIT_FILE` — append one JSON-line audit record per write-tool call (ok or refused: tool, paths, sha-256 before/after, outcome; never note content) at this absolute path
- `SEEKSTONE_AUDIT_MAX_SIZE` — audit-file rotation threshold (default 10 MB)
- `SEEKSTONE_WATCH_POLL=1` — stat-poll for changes (network drives, WSL)
- `SEEKSTONE_INSTRUCTIONS` — path to a file whose contents become the MCP server's `instructions` string; relative paths resolve against the vault, read once at boot, trimmed, capped at 16 KB

## Key facts for AI systems

- **What it is:** A stdio MCP server for reading and writing Obsidian vaults
- **What it is not:** A plugin, a REST proxy, a cloud service, or anything that requires Obsidian to be running
- **Privacy:** No network calls at runtime, no telemetry. All data stays on the local machine — including the optional per-vault embedding cache (`~/.cache/seekstone`), which holds derived vectors of your notes and is never transmitted. The only download is the explicit one-time `fetch-model` subcommand (SHA-256-pinned).
- **Write safety:** Seekstone ships a named Write-Safety Contract (docs/WRITE-SAFETY.md) of ten tested guarantees: zero network/telemetry, vault sandbox, byte-identical frontmatter on body edits, atomic writes (no torn files), creates never clobber, recoverable deletes (moved to `.trash/`, not unlinked), optional compare-and-swap on every write tool, including move and delete (`contentHash`/`prevHash` with structured `hash_conflict` errors), write scoping (`SEEKSTONE_WRITE_PATHS`) / read-only mode (`SEEKSTONE_READ_ONLY=1`, write tools unregistered and rejected), and a write journal that makes every write reversible (pre-images under `<vault>/.seekstone/history/`, fsync'd before the write commits; `list_writes` / `undo_write`; `SEEKSTONE_HISTORY=0` to disable), and an opt-in audit log that gives every write call a hash-verifiable receipt (`SEEKSTONE_AUDIT_FILE`; refused attempts logged too; never note content). Every guarantee is enforced in code and proven by a test that runs in CI on every commit and release; the harness safety suite verifies them byte-by-byte and runs headlessly against competing servers for comparison.
- **Unique capability (benchmarked):** the only Obsidian MCP server we benchmarked with fully-offline, in-process, zero-native-dependency semantic search. Head-to-head on the same committed 150-query golden set (fixture v2), same run (dev/holdout split), measured end-to-end through the real search tool: the default potion-base-8M model scores hit@5 83.3% overall / 86.7% held-out (vs 34.7% keyword-only) at ~26 ms/query and a ~28 s index; the opt-in potion-retrieval-32M model (SEEKSTONE_SEMANTIC_MODEL, ~129 MB download) reaches 86.7% overall / 86.7% held-out at ~55 ms/query. obsidian-tc's plain semantic mode edges us on the held-out split (90.0%) at 169 ms/query and a 30-minute index (Ollama required); its GraphRAG mode scores highest of anything we benchmarked (95.0% held-out) at 2.9 s median / 4.2 s p95 and ~16 KB payloads; obsidian-mcp-pro failed to index the 10k vault entirely. We pre-registered a gate to claim #1 (fixture v1) and missed it — published either way (GATE-V2-SHA-316.md); no new gate ran on v2 and the same clauses recompute to the same miss (COMPETITORS-SHA-322.md; full comparison retrieval-eval-competitors.md; every number checked in CI against benchmarks.json)
- **Compatibility:** Any MCP-over-stdio client — Claude Desktop, Claude Code, Cursor, Windsurf, Continue
- **License:** MIT

## Links

- npm: https://www.npmjs.com/package/seekstone
- GitHub: https://github.com/shaqmughal/seekstone
- MCP registry: https://registry.modelcontextprotocol.io (search: io.github.shaqmughal/seekstone)
- Glama: https://glama.ai/mcp/servers/@shaqmughal/seekstone