# shaqmughal/seekstone [Health: Active]
**Category:** π οΈ Other Tools and Integrations
**Repository:** https://github.com/shaqmughal/seekstone
**GitHub Stars:** 26
**npm Downloads (last month):** 4620
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/shaqmughal-seekstone
## Description
Filesystem-direct Obsidian MCP server with low context-tax. Reads your vault directly from disk β no Local REST API plugin required. 575Γ smaller payloads than the REST plugin. 8 tools. npx -y obsidian-mcp-seekstone (also: npx -y seekstone)
## Tools
Capabilities this server exposes over MCP:
- **search** β Full-text search. Returns ranked excerpts (default ~120 chars, tunable via `excerptLength`), not full notes. Fuzzy and prefix matching; with `SEEKSTONE_SEMANTIC=1`, `mode: "semantic"`/`"hybrid"` searches by meaning via a local embedding model (nothing leaves your machine).
- **query_notes** β Structured metadata query. Filter by frontmatter key/value predicates (`eq`, `ne`, `contains`, `exists`, `missing`, `gt`/`gte`/`lt`/`lte`), tag, folder, modified time, and size; sort and select the fields you need. 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 2 KB): ranked excerpts, linked neighbor notes with one-line summaries, and follow-up source paths β replaces a search β read β get_backlinks round-trip loop.
- **read_note** β Read the full content of a note by vault-relative path. Supports returning a single section, block, or line range.
- **list_notes** β List notes, optionally filtered by folder prefix or tag.
- **list_tags** β List all tags in the vault sorted by usage count (or alphabetically).
- **outline_note** β Return a note's heading and block structure without its full content β cheap navigation before a targeted read.
- **get_backlinks** β Find all notes that link to a given note.
- **get_links** β List all outgoing wikilinks and markdown links from a note.
- **get_periodic_note** β Read today's (or any date's) daily, weekly, monthly, quarterly, or yearly note β path resolved from your vault config, no Obsidian required.
- **list_writes** β Recent writes from the journal β seq, timestamp, tool, touched paths, and whether each is still undoable. Metadata only, never note content.
- **create_note** β Create a note (optional frontmatter + body); parent directories are created automatically.
- **delete_note** β Move a note to the vault's `.trash/` folder (Obsidian-compatible, restorable). Pass `permanent: true` to skip the trash β the write journal still lets `undo_write` restore it.
- **move_note** β Move or rename a note β wikilinks and markdown links in other notes that point at it are rewritten so nothing breaks (`rewriteLinks: false` to opt out); destination directories are created automatically.
- **rename_heading** β Rename a heading in a note β every `[[note#heading]]` wikilink and embed across the vault is rewritten so references keep working (aliases preserved, fenced code blocks left alone).
- **append_note** β Append text to a note body without touching frontmatter.
- **patch_frontmatter** β Set, update, or delete frontmatter keys without reordering existing keys or changing quote style.
- **patch_note** β Append, prepend, or replace text at a heading or block reference (`createIfMissing` to add the section) β frontmatter untouched.
- **replace_in_note** β Find and replace text in the note body β literal or regex, case sensitivity, whole-word matching, optional `limit` (replaces **all** occurrences by default), and a dry-run preview.
- **append_periodic_note** β Append to today's periodic note, creating it from a template if it doesn't yet exist.
- **undo_write** β Revert a journaled write: every file it touched goes back to its byte-identical pre-write state (a multi-file move or heading rename is restored whole; a delete is restored even if it was `permanent`). Defaults to the most recent write; refuses with `undo_conflict` if a file changed since, unless `β¦
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):
```json
"mcpServers": {
"seekstone": {
"command": "npx",
"args": ["-y","seekstone"]
}
}
```
## Documentation & README
The Obsidian MCP server that needs no plugin, no running Obsidian app β and doesn't blow your context window.
Filesystem-direct Β· single-digit-ms keyword search Β· ~26 ms semantic Β· ~2 KB payloads Β· 21 tools Β· macOS Β· Linux Β· Windows
seekstone.dev β
---
| | **Seekstone** | [obsidian-mcp-server](https://github.com/cyanheads/obsidian-mcp-server) (#1 by downloads) | REST-proxy servers |
|---|---|---|---|
| Local REST API plugin | **Not needed** | Required | Required |
| Obsidian app running | **Not needed β works with Obsidian closed** | Required | Required |
| Search payload @ 10k notes | **2.0 KB** | 47 KB | up to **95 MB** |
| Warm search latency @ 10k notes | **5.2 ms** | 732 ms (~141Γ slower) | up to 1,550 ms |
| Structured frontmatter queries | **Built-in (`query_notes`) β property/date/size predicates, answers in a few hundred bytes** | JSONLogic via REST | Varies |
Same queries, same committed vaults, 20 runs each, one machine. In-process adapters were re-run on the fixture-v2 vault in September 2026; the REST-proxy rows (`rest`, obsidian-mcp-server, mcp-obsidian) plus obsidian-mcp and obsidian-mcp-pro are June 2026 captures on fixture v1 β per-row provenance in [`benchmarks.json`](https://github.com/shaqmughal/seekstone/blob/HEAD/benchmarks.json), the generated source of truth every number here is checked against in CI β [full results across eight servers and three vault sizes below](#why-seekstone-the-numbers), fully reproducible from the [harness](https://github.com/shaqmughal/seekstone/blob/HEAD/packages/harness).
---
---
## What is Seekstone?
**Seekstone is an Obsidian MCP server** β it gives Claude (and any [Model Context Protocol](https://modelcontextprotocol.io) client) direct read and write access to your Obsidian vault. No Obsidian app needs to be open, no plugins are required, and nothing leaves your machine.
It reads your vault **directly from disk** rather than routing through the Obsidian Local REST API plugin, and holds a warm full-text index in-process. The practical difference is twofold:
- **Speed.** Keyword searches return in **single-digit milliseconds** warm and semantic searches in **~26 ms** β up to **~514Γ faster** than every other Obsidian MCP server we benchmarked, because there's no subprocess to spawn and no HTTP round-trip per query.
- **Context.** A broad search that returns **tens of megabytes** and millions of tokens via a REST-proxy server returns **~2 KB** via Seekstone β up to a **~47,000Γ reduction** that only widens as your vault grows.
Search comes in three modes: ranked **full-text search** (fuzzy and prefix matching), optional **local semantic search** (meaning-based, via a small on-device embedding model β opt-in, offline at runtime after a one-time ~30 MB model download), and **structured metadata queries** β `query_notes` filters by frontmatter properties (`status`, `due`, `type`, β¦), tags, folder, modified time, and size, answering questions like *"which draft notes changed this week?"* in a few hundred bytes instead of a search-and-read loop.
Claude can search and read your entire note library, in milliseconds, without burning most of its context window on a single tool call.
Published on npm as [`seekstone`](https://www.npmjs.com/package/seekstone) β install with `npx -y seekstone`. (Previously also published as `obsidian-mcp-seekstone`; that alias is deprecated but existing installs keep working.)
---
## Why Seekstone? The numbers.
Most Obsidian MCP servers return **full note content for every search hit**. On a broad query that's megabytes of text your LLM has to process β most of it irrelevant, all of it burning context window.
Seekstone returns short ranked excerpts instead (~120 characters by default, tunable per query). We benchmarked Seekstone against 7 other Obsidian MCP servers β 8 servers total β across **three vault sizes β 1,000 / 5,000 / 10,000 notes** (20 runs each). Every number below is [fully reproducible](https://github.com/shaqmughal/seekstone/blob/HEAD/packages/harness): the vaults are committed to this repo (generated from the public-domain 1911 EncyclopΓ¦dia Britannica), so you can clone it and run the exact same benchmark yourself.
The point of testing three sizes is that **this is where the architectures diverge** β a real vault only grows.
**Search payload β bytes returned per query (context tax; lower is better)**
| Server | Architecture | 1k notes | 5k notes | 10k notes |
|---|---|---:|---:|---:|
| π₯ **Seekstone** | in-process index | **1.6 KB** | **1.8 KB** | **2.0 KB** |
| [mcpvault](https://github.com/bitbonsai/mcpvault) | fs-direct subprocess | 1.7 KB | 1.9 KB | 2.2 KB |
| [obsidian-mcp-rs](https://www.npmjs.com/package/obsidian-mcp-rs) | fs-direct, per-query scan | 5.4 KB | 5.8 KB | 6.2 KB |
| [obsidian-tc](https://www.npmjs.com/package/obsidian-tc) | SQLite platform | 4.6 KB | 6.8 KB | 7.2 KB |
| [obsidian-mcp-server](https://github.com/cyanheads/obsidian-mcp-server) | REST API | 55 KB | 47 KB | 47 KB |
| [obsidian-mcp-pro](https://github.com/rps321321/obsidian-mcp-pro) | fs-direct subprocess | 25 KB | 84 KB | 114 KB |
| [obsidian-mcp](https://github.com/StevenStavrakis/obsidian-mcp) | fs-direct subprocess | 18 KB | 105 KB | 201 KB |
| [mcp-obsidian](https://github.com/MarkusPfundstein/mcp-obsidian) | REST API | 9.8 MB | 45 MB | **95 MB** |
Seekstone stays **flat (~2 KB)** no matter how big your vault gets, because it always returns ranked excerpts β and it's now the **smallest payload of every server tested**, edging out mcpvault at all three sizes. The REST-proxy servers return full note content for every match, so they grow with the vault β `mcp-obsidian` hits **95 MB** at 10k notes, and a single broad query (`the capital of`) averaged **370.9 MB / 97.8 million tokens** per call across 20 runs. At 10k notes that's a **~47,000Γ context-tax difference**.
**Search latency β warm mean, ms (lower is better)**
| Server | 1k notes | 5k notes | 10k notes | vs Seekstone @10k |
|---|---:|---:|---:|---|
| π₯ **Seekstone** | **1.0** | **2.7** | **5.2** | **β** |
| obsidian-mcp-rs | 5.8 | 18 | 35 | ~7Γ slower |
| obsidian-mcp-pro | 46 | 213 | 430 | ~83Γ slower |
| obsidian-mcp-server | 82 | 356 | 732 | ~141Γ slower |
| obsidian-mcp | 82 | 405 | 811 | ~156Γ slower |
| mcpvault | 89 | 436 | 897 | ~173Γ slower |
| mcp-obsidian | 164 | 740 | 1,550 | ~299Γ slower |
| obsidian-tc | 263 | 1,253 | 2,667 | ~514Γ slower |
Every competitor spawns a subprocess or makes HTTP round-trips per query, and most do work that scales with vault size. Seekstone holds a warm in-process index β **no IPC, no network** β so keyword search stays in **single-digit milliseconds** even at 10,000 notes (the shipped semantic pipeline β embed, scan, MaxSim rerank β lands at ~26 ms). And the gap **widens with scale**: from 1k β 10k notes the competitors slow down 5β10Γ, while Seekstone barely moves. Even the *fastest* alternative β [obsidian-mcp-rs](https://www.npmjs.com/package/obsidian-mcp-rs), which re-scans the vault on every query β is **~7Γ slower** warm at 10k notes with **3Γ the payload**, and the REST-proxy generation runs **~110β300Γ slower**.
**Seekstone is the only server in our benchmark set that delivers both ~2 KB payloads and single-digit-ms keyword latency at every vault size** β and, as far as we know, the only Obsidian MCP server with published, reproducible benchmarks. The harness, the synthetic vaults, and the full results are open source: see [`benchmark-scaling.md`](https://github.com/shaqmughal/seekstone/blob/HEAD/packages/harness/fixtures/baseline-reports/scaling/benchmark-scaling.md) and the [harness](https://github.com/shaqmughal/seekstone/blob/HEAD/packages/harness). Clone, run, verify.
---
## Install
Choose the method that suits you best.
### Using an AI agent? Paste this prompt
If you use Claude Code, Cursor, or another coding agent, you don't need to follow any instructions yourself β paste this prompt and the agent does the install:
> 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 ""`. Relay any errors to me, then tell me to restart this session so the seekstone tools load.
`seekstone init` is fully non-interactive β with `--write` it validates the vault and patches the client config in one shot (Claude Code via `claude mcp add`, other clients via an additive JSON patch with a timestamped backup).
### Option 1 β One-click (Claude Desktop, no terminal needed)
1. Download [`seekstone.mcpb`](https://github.com/shaqmughal/seekstone/releases/latest/download/seekstone.mcpb) (direct link, always the latest release)
2. Open it with Claude Desktop β double-click in Finder, or right-click β Open With β Claude Desktop
3. Pick your Obsidian vault folder when prompted
You'll know it worked when seekstone appears in Claude's toolbar. No JSON editing, no terminal, no Node.js required.
Want semantic search? Grab [**`seekstone-semantic.mcpb`**](https://github.com/shaqmughal/seekstone/releases/latest/download/seekstone-semantic.mcpb) instead β same server with the local embedding model shipped inside the bundle (~28 MB bigger), so meaning-based search works out of the box: still no terminal, and nothing is downloaded at runtime.
/.cursor/mcp.json` (per-project):
```json
{
"mcpServers": {
"seekstone": {
"command": "npx",
"args": ["-y", "seekstone"],
"env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
}
}
}
```
### Option 6 β VS Code
One-click: /.seekstone/history/` β content-addressed (identical states are stored once) and fsync'd before the vault write commits. `list_writes` shows the journal; `undo_write` restores byte-identically: a multi-file `move_note` or `rename_heading` is restored whole (the note *and* every link rewrite), and a `delete_note` comes back even if it was `permanent`. An undo after an external edit is refused with a structured `undo_conflict` unless you pass `force: true` β and even then the clobbered state is journaled first, so nothing is ever lost. Undo is itself journaled: repeated default undos walk backwards through the history, and `undo_write({ seq })` on an undo entry redoes it. `.seekstone/` is excluded from indexing and search like `.trash/`; add it to your vault's `.gitignore`. This complements git and Obsidian's File Recovery rather than replacing them β it is the recovery path the *agent* can drive.
**Every write leaves a receipt.** Set `SEEKSTONE_AUDIT_FILE` and every write-tool call β successful *or refused* β appends one JSON line: tool, vault-relative paths, sha-256 before/after, outcome (`ok`, `hash_conflict`, `undo_conflict`, `policy_denied`, `error`), and op metadata such as replacement counts or the `.trash/` destination β never note content, frontmatter values, or search queries, so the file is safe to attach to a bug report.
```jsonl
{"v":1,"ts":"2026-08-29T21:02:11.042Z","tool":"replace_in_note","outcome":"ok","durationMs":1.8,"seq":42,"files":[{"path":"notes/a.md","hashBefore":"3f9cβ¦","hashAfter":"b71eβ¦"}],"path":"notes/a.md","replacements":3}
```
The hashes are the same `contentHash` values `read_note` returns, so any record can be checked against the vault; `seq` is the journal entry the call committed, so a row indexes straight into `list_writes` / `undo_write`. Records are appended and fsync'd after the vault write commits, the file rotates to `.1` past `SEEKSTONE_AUDIT_MAX_SIZE`, an unwritable audit path fails boot, and a failed append reports the call as a structured `audit_failed` error rather than a clean success. A few `jq` recipes:
```bash
jq -r '[.tool, .outcome] | @tsv' audit.jsonl | sort | uniq -c # session summary by tool + outcome
jq -c 'select(.files[]?.path == "notes/a.md")' audit.jsonl # history of one note
jq -c 'select(.ts > "2026-08-29T21:00:00Z" and .outcome == "ok")' audit.jsonl # what changed since a timestamp
```
**Fast *and* complete.** Seekstone is the only Obsidian MCP server in our benchmark set to expose `list_tags`, `outline_note`, `get_backlinks`, and `get_links` as first-class tools. Four more capabilities set it apart:
- **Local semantic search, fully in-process.** With `SEEKSTONE_SEMANTIC=1`, `search` gains `mode: "semantic"` and `"hybrid"` β meaning-based retrieval through a small on-device embedding model (one-time `npx -y seekstone fetch-model` download, or the `seekstone-semantic.mcpb` bundle which ships the model inside; the running server never touches the network), with a MaxSim late-interaction rerank on top since 0.17.0. On our committed 10k-note benchmark vault (150-query golden set, fixture v2), the default model β measured end-to-end through the real search tool β scores **83.3% overall hit@5, 86.7% on the held-out split** (vs 34.7% for keyword search alone) at ~26 ms warm p50, and the opt-in `potion-retrieval-32M` model (`SEEKSTONE_SEMANTIC_MODEL`; ~129 MB) reaches **86.7% overall hit@5, 86.7% held-out** at ~55 ms. No other server we **benchmarked** ships offline, zero-native-dependency embeddings β and we measured the alternatives head-to-head on the same golden set, same run, committed dev/holdout split ([committed comparison](https://github.com/shaqmughal/seekstone/blob/HEAD/packages/harness/fixtures/baseline-reports/retrieval-eval-competitors.md), read-out in [COMPETITORS-SHA-322](https://github.com/shaqmughal/seekstone/blob/HEAD/packages/harness/fixtures/baseline-reports/COMPETITORS-SHA-322.md)): obsidian-tc's plain Ollama-backed semantic search **edges us on the held-out split** (90.0% vs our 86.7%) at 169 ms/query and a 30-minute index vs our ~28 s, and its GraphRAG mode **scores highest of anything we benchmarked** (95.0% held-out), paying for it with **seconds-per-query latency** (2.9 s p50, 4.2 s p95 β against our 26β55 ms), **~8Γ the payload** (16 KB vs ~2 KB per query), and a second server (Ollama + a 137M-parameter model) you must install and run. We pre-registered a gate to claim the #1 spot ([GATE-V2-SHA-316](https://github.com/shaqmughal/seekstone/blob/HEAD/packages/harness/fixtures/baseline-reports/GATE-V2-SHA-316.md), run on fixture v1) and **missed it β that verdict is published with the same prominence a win would have been**; no new gate ran on v2, and the same clauses recompute to the same miss. obsidian-mcp-pro could not index the 10k-note vault at all (its JSON vector store exceeds JavaScript's string limit after ~17 minutes of embedding). Pick your trade β the numbers are all committed.
- **Periodic notes, filesystem-direct.** `get_periodic_note` and `append_periodic_note` resolve daily, weekly, monthly, quarterly, and yearly note paths by reading your vault's own config (`.obsidian/daily-notes.json` and the Periodic Notes plugin) β **with Obsidian closed.** Every REST-based server can only do this while the app is running.
- **Byte-identical frontmatter, guaranteed.** `patch_frontmatter` edits YAML in place β preserving key order, quote style, and comments β and write-safety is proven byte-for-byte by the test harness. No other server we surveyed makes this guarantee.
- **Zero coupling.** No Obsidian app, no Local REST API plugin, no plugin-version drift. Just your files on disk.
---
## Configuration
| Variable | Required | Description |
|---|---|---|
| `SEEKSTONE_VAULT` | Yes | Absolute path to your Obsidian vault. |
| `SEEKSTONE_LOG_LEVEL` | No | `error` \| `warn` \| `info` (default) \| `debug`. |
| `SEEKSTONE_LOG_FILE` | No | Absolute path; when set, JSON-line logs are appended here (size-rotated). |
| `SEEKSTONE_LOG_MAX_SIZE` | No | Log-rotation threshold for `SEEKSTONE_LOG_FILE` (e.g. `10mb`; default 5 MB). |
| `SEEKSTONE_WATCH_POLL` | No | Set to `1` to stat-poll for changes instead of native OS events β slower but reliable on network drives, WSL, and some containers. |
| `SEEKSTONE_WATCH_POLL_INTERVAL` | No | Stat-poll interval in ms (default `10000`). Only used with `SEEKSTONE_WATCH_POLL=1`. Lower = faster pickup of external edits, higher CPU; raise it on slow network/9p mounts. |
| `SEEKSTONE_READ_ONLY` | No | Set to `1` to run read-only: the 10 write tools are unregistered from the tool list entirely (and rejected if called anyway), so the session provably cannot modify your vault. |
| `SEEKSTONE_WRITE_PATHS` | No | Comma-separated vault-relative globs (e.g. `journal/**,inbox/*.md`). Writes are permitted only under matching paths; the rest of the vault stays read-only. |
| `SEEKSTONE_HISTORY` | No | Set to `0` to disable the write journal (default on). With it on, every write tool stores the pre-image of each file it touches under `/.seekstone/history/` so `undo_write` can restore it byte-for-byte. |
| `SEEKSTONE_HISTORY_MAX_SIZE` | No | Cap on stored pre-images (e.g. `100mb`; default 50 MB). Oldest entries are evicted first and then show `undoable: false` in `list_writes` β never silently. |
| `SEEKSTONE_HISTORY_MAX_ENTRIES` | No | Cap on journal entries (default `1000`); the oldest are dropped past it. |
| `SEEKSTONE_AUDIT_FILE` | No | Absolute path; off unless set. Appends one JSON-line audit record per write-tool call β ok or refused β with the tool, paths, sha-256 before/after, outcome, and op metadata. Never note content. |
| `SEEKSTONE_AUDIT_MAX_SIZE` | No | Rotate the audit file to `.1` past this size (e.g. `10mb`; default 10 MB). |
| `SEEKSTONE_SEMANTIC` | No | Set to `1` to enable semantic search (`search` gains `mode: "semantic"` and `"hybrid"`). Requires the local embedding model β download it once with `npx -y seekstone fetch-model`; the running server never touches the network. The `seekstone-semantic.mcpb` bundle sets this automatically and ships the model inside. |
| `SEEKSTONE_SEMANTIC_MODEL` | No | Which local model to load: `potion-base-8M` (default, ~30 MB, 256-dim) or `potion-retrieval-32M` (~129 MB, 512-dim β more accurate on description-style queries at roughly 2Γ the query latency). Fetch it first with `npx -y seekstone fetch-model --model potion-retrieval-32M`. |
| `SEEKSTONE_MODEL_PATH` | No | Directory holding the Model2Vec embedding model (default: where `fetch-model` puts the selected model, under the cache dir). |
| `SEEKSTONE_CACHE_DIR` | No | Cache root for the downloaded model and per-vault embedding caches (default `~/.cache/seekstone`). |
| `SEEKSTONE_BUNDLED_MODEL_DIR` | No | Set by the `seekstone-semantic.mcpb` bundle's manifest β points at the sharded model files shipped inside the extension, which the server reassembles into the model directory at boot (disk-only, verified against the pinned SHA-256 hashes). Not usually set by hand. |
---
## How it works
Seekstone walks the vault with `fast-glob`, parses each note's frontmatter (byte-aware, so writes can prove the frontmatter region is byte-identical pre- and post-write), and builds a [MiniSearch](https://github.com/lucaong/minisearch) full-text index in memory. Search returns short ranked excerpts rather than whole notes β that excerpt-not-document design is where the context-tax win comes from. A cross-platform file watcher ([chokidar](https://github.com/paulmillr/chokidar)) keeps the index current as you edit in Obsidian.
Writes are conservative by design: `append_note` never touches frontmatter, and `patch_frontmatter` edits the YAML document in place rather than re-serializing it, preserving key order, quote style, and comments.
It's built to stay up. Seekstone is tested on macOS, Linux, and Windows in CI on every commit, its write tools are hardened against pathological (ReDoS) inputs, and a stray unhandled rejection is logged rather than crashed on β so your long-lived MCP session keeps its warm index instead of dropping out mid-conversation.
For a layer-by-layer tour of the codebase β packages, the server's internals, the end-to-end request flow, and the measurement harness β see [`docs/ARCHITECTURE.md`](https://github.com/shaqmughal/seekstone/blob/HEAD/docs/ARCHITECTURE.md).
---
## Security & privacy
Seekstone reads β and, via the write tools, modifies β files under `SEEKSTONE_VAULT` on your local disk. The running server makes **no network calls** and sends **no telemetry** (the one network path in the package is the explicit `npx -y seekstone fetch-model` subcommand β a SHA-256-verified, one-time download of the optional semantic-search model that exits before serving starts; the `seekstone-semantic.mcpb` bundle skips even that by shipping the model inside and reassembling it from disk at boot, verified against the same pinned hashes). Logs are metadata-only by default (note contents only appear at `debug` level). Nothing is written outside the vault except an optional log file you configure and, with `SEEKSTONE_SEMANTIC=1`, the per-vault embedding cache under `~/.cache/seekstone` (derived vectors of your notes β never sent anywhere).
### The Write-Safety Contract
Giving an AI write access to your notes deserves more than "trust us." Seekstone ships a named, tested contract β [`docs/WRITE-SAFETY.md`](https://github.com/shaqmughal/seekstone/blob/HEAD/docs/WRITE-SAFETY.md) β of **ten guarantees, each linked to the code that enforces it and the test that proves it**, verified byte-by-byte by the harness safety suite in CI on every commit and release: zero network, vault sandbox, byte-identical frontmatter on body edits, atomic writes (no torn files), creates never clobber, recoverable deletes (`.trash/`), optional compare-and-swap on every write tool, configurable write scoping / read-only mode, a write journal that makes every write reversible (`undo_write`), and a hash-verifiable audit log β every write call leaves a receipt. The same suite runs headlessly against other FS-direct servers β the comparison table is in the contract.
---
## Frequently asked questions
**Does the Obsidian app need to be running?**
No. Seekstone reads the vault folder directly from disk. Obsidian can be open or closed.
**Do I need the Local REST API plugin?**
No. Seekstone bypasses it entirely β that's the source of the up-to-47,000Γ payload reduction. No plugins are required.
**Which AI clients does it support?**
Any client that supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) over stdio β Claude Desktop, Claude Code, Cursor, Windsurf, Continue, and others.
**Is it safe to use on my vault?**
Seekstone never modifies files except when you explicitly invoke one of its write tools (the ten in the table above β `create_note`, `append_note`, `patch_note`, `patch_frontmatter`, `replace_in_note`, `move_note`, `rename_heading`, `delete_note`, `append_periodic_note`, `undo_write`). Every one of them journals the pre-image of each file it touches first, so `undo_write` can put it back byte-for-byte β see the write-journal note above β and with `SEEKSTONE_AUDIT_FILE` set, every write call leaves a hash-verifiable audit record (refused attempts included). The running server makes no network requests (semantic search's model is fetched once, out-of-band, by the explicit `fetch-model` subcommand). The vault path is sandboxed β no tool can read or write outside it. And you can tighten it further: `SEEKSTONE_READ_ONLY=1` removes the write tools from the session entirely, and `SEEKSTONE_WRITE_PATHS` restricts writes to the folders you allow (say, only `journal/**`). Both are enforced at the dispatch layer, not per-tool, so no tool can forget the check.
**Does it work on Windows?**
Yes. Seekstone is tested on macOS, Linux, and Windows in CI on every commit.
**What Obsidian vault sizes does it handle?**
Seekstone has been profiled against vaults with thousands of notes. On the committed 10,000-note benchmark vault, the cold index build takes tens of seconds and process RSS lands under ~100 MB; typical personal vaults index in a few seconds. Semantic mode embeds in the background after boot (~30 s at 10k notes, then cached per-vault so restarts reload in well under a second).
**How does `seekstone init` find my vault automatically?**
It reads Obsidian's own vault registry (`obsidian.json`) β the same file Obsidian uses to track your known vaults. If you have one vault, it's selected automatically. If you have multiple, it lists them and asks you to pick with `--vault`.
**What is the `.mcpb` file?**
An MCP Bundle β a self-contained zip with the server and its manifest. To install: double-click in Finder (or right-click β Open With β Claude Desktop), pick your vault, and you're done. No terminal or Node.js required. Two variants ship with every release: [`seekstone.mcpb`](https://github.com/shaqmughal/seekstone/releases/latest/download/seekstone.mcpb) (standard) and [`seekstone-semantic.mcpb`](https://github.com/shaqmughal/seekstone/releases/latest/download/seekstone-semantic.mcpb) (same server with the local embedding model inside, semantic search on out of the box).
---
## Contributing & development
Contributions welcome. See [CONTRIBUTING.md](https://github.com/shaqmughal/seekstone/blob/HEAD/CONTRIBUTING.md) for guidelines, or jump straight in:
```bash
npm install # install all workspace deps
npm test # run all tests
npm run lint # biome check
npm run build -w seekstone # tsup β dist/
npm run build:mcpb # build seekstone.mcpb bundle
npx vitest run packages/server/src/tools/search.test.ts # single test file
npx vitest run -t 'parses a typical frontmatter' # single test by name
npx tsc -p packages/server/tsconfig.json --noEmit # typecheck
```
### Repository layout
| Package | Purpose |
|---|---|
| `packages/server` | The published `seekstone` MCP server (21 tools, stdio, MiniSearch index, chokidar watcher). |
| `packages/core` | Shared vault primitives β walk, frontmatter parser, link/tag extractor, outline, percentiles, pmap, and the Model2Vec embedder. Bundled into the server build. |
| `packages/harness` | Profiler + benchmark + write-safety harness (REST vs filesystem) that produced the payload numbers above. Dev-only; not published. |
The server has a real build (tsup β `dist/`) and is published to npm. The harness is run from source via `tsx`. Releases are automated β see [docs/RELEASING.md](https://github.com/shaqmughal/seekstone/blob/HEAD/docs/RELEASING.md).
### The measurement harness
The harness exists to reproduce the benchmark numbers that motivated the filesystem-direct design. The default reproduction path (`fs`/`seekstone` backends against the committed synthetic vault) needs nothing extra; only the REST-backed backends (`rest`, `mcp-obsidian`, `obsidian-mcp-server`) need Obsidian running with the Local REST API plugin.
```bash
export SEEKSTONE_VAULT="/absolute/path/to/your/vault"
npx tsx packages/harness/src/cli.ts profile --vault "$SEEKSTONE_VAULT"
npx tsx packages/harness/src/cli.ts bench \
--queries packages/harness/queries/default.json \
--stats reports/vault-stats.json
npx tsx packages/harness/src/cli.ts safety --vault "$SEEKSTONE_VAULT"
```
Harness env vars: `SEEKSTONE_REST_API_KEY` (from the Local REST API plugin) and `SEEKSTONE_REST_URL` (defaults to `https://127.0.0.1:27124`).
---
## Support
Seekstone is free and open source. If it saves you context (and money), you can [buy me a coffee](https://buymeacoffee.com/shaqmughal).
---
## License
MIT Β© Shaq Mughal
### Option 2 β Guided setup (recommended for CLI users)
Open **Terminal** (macOS: `Cmd+Space`, type "Terminal", press Enter) and run:
```bash
npx -y seekstone init
```
You'll know it worked when Seekstone appears in Claude's toolbar under the plug icon.
Seekstone reads Obsidian's own vault registry to detect your vault, validates it, and either prints the config block to paste or patches Claude Desktop directly:
```bash
# Auto-detect vault, print config to paste
npx -y seekstone init
# Auto-detect vault, patch Claude Desktop in place (with backup)
npx -y seekstone init --write
# Specify vault explicitly if you have multiple
npx -y seekstone init --vault "/path/to/vault"
# Auto-configure Claude Code in one step (auto-detects vault, runs claude mcp add)
npx -y seekstone init --client code --write
# Or just print the Claude Code command without running it
npx -y seekstone init --client code
```
### Option 3 β Manual config (Claude Desktop)
Add to `claude_desktop_config.json` (Settings β Developer β Edit Config):
```json
{
"mcpServers": {
"seekstone": {
"command": "npx",
"args": ["-y", "seekstone"],
"env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
}
}
}
```
### Option 4 β Claude Code
Auto-detects your vault and configures Claude Code in one command:
```bash
npx -y seekstone init --client code --write
```
Or manually, if you prefer to specify the vault path explicitly:
```bash
claude mcp add seekstone --env SEEKSTONE_VAULT=/absolute/path/to/your/vault -- npx -y seekstone
```
### Option 5 β Cursor
One-click: