seekstone

Seekstone reads your Obsidian vault directly from disk instead of routing through the Obsidian Local REST API plugin. The practical difference: a search that returns ~1.75 MB and ~459,000 tokens via the REST plugin returns ~3 KB and ~800 tokens via seekstone — a ~575× reduction. The payoff is that Claude can search and read notes without burning most of its context window on a single tool call.

It runs as a standard MCP stdio server. No Obsidian app and no plugins required — just point it at a vault folder.

Install

Claude Desktop — add to claude_desktop_config.json (Settings → Developer → Edit Config):

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

Claude Code:

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

Restart the client. On startup seekstone walks the vault and builds an in-memory full-text index (a couple of seconds for a few thousand notes), then keeps it in sync as notes change. The eight tools below are then available to Claude.

Requires Node.js ≥ 22. Works on macOS, Linux, and Windows.

To confirm the package is reachable before wiring it into a client, run npx -y seekstone --version (prints the version and exits) or npx -y seekstone --help.

Guided setup

Prefer not to hand-edit JSON? seekstone init validates your vault and prints the exact config to paste — or patches the Claude Desktop config for you:

# Validate the vault and print the config block to copy
npx -y seekstone init --vault "/absolute/path/to/your/vault"

# Or patch the Claude Desktop config in place (backs it up first, never
# touches your other MCP servers)
npx -y seekstone init --vault "/absolute/path/to/your/vault" --write

# Print the Claude Code command instead
npx -y seekstone init --vault "/absolute/path/to/your/vault" --client code

Tools

Configuration

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), and builds a 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) keeps the index current as you edit.

Writes are conservative by design: append_note never touches frontmatter, and patch_frontmatter preserves key order, quote style, and comments (it edits the YAML document in place rather than re-serializing it).

Security & privacy

Seekstone reads — and, via the write tools, modifies — files under SEEKSTONE_VAULT on your local disk. It makes no network calls and sends no telemetry. Logs are metadata-only by default (note contents appear only at debug). Nothing is written outside the vault except an optional log file you configure. Note that delete_note is irreversible.

Contributing & development

Contributions welcome — see CONTRIBUTING.md if present, otherwise:

npm install        # install all workspace deps
npm test           # run all tests
npm run lint       # biome
npm run build -w seekstone   # build the publishable server (tsup → dist/)

npx vitest run packages/server/src/tools/search.test.ts   # a single test file
npx vitest run -t 'parses a typical frontmatter'          # a single test by name
npx tsc -p packages/server/tsconfig.json --noEmit         # typecheck

Repository layout

The server has a real build (tsup → dist/) and is published to npm. The harness is run from source via tsx and is not published. Releases are automated — see docs/RELEASING.md.

The harness

The harness measures the thing the server is designed around: payload size. It needs the Local REST API plugin for the rest backend.

export SEEKSTONE_VAULT="/absolute/path/to/your/vault"

# Profile vault shape
npx tsx packages/harness/src/cli.ts profile --vault "$SEEKSTONE_VAULT"

# Benchmark adapters (filesystem vs REST)
npx tsx packages/harness/src/cli.ts bench \
  --queries packages/harness/queries/default.json \
  --stats reports/vault-stats.json

# Write-safety suite
npx tsx packages/harness/src/cli.ts safety --vault "$SEEKSTONE_VAULT"

Harness-specific env vars: SEEKSTONE_REST_API_KEY (required for the rest backend, from the Local REST API plugin) and SEEKSTONE_REST_URL (defaults to https://127.0.0.1:27124).

License

MIT © Shaq Mughal