Seekstone Obsidian Mcp Server
About
Seekstone is a filesystem-direct Obsidian MCP server that gives Claude (and any MCP client) direct read/write access to your Obsidian vault — straight from the filesystem. No running Obsidian instance, no REST API plugin, no proxy.
Details
- Author
- shaqmughal
- Downloads
- 322
- Categories
- File Management, Search, Knowledge Base, Developer Tools, Productivity
Jump to
—
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Seekstone Obsidian Mcp ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
—
search
Full-text search across the vault. Returns ranked excerpts (~200 chars) — not full notes — to minimise context usage. Supports fuzzy matching and prefix search; with SEEKSTONE_SEMANTIC=1, mode "semantic"/"hybrid" searches by meaning via a local embedding model.
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; opt into more via select), not note content. Use this instead of search when filtering by properties rather than text.
context_pack
Assemble everything needed to ANSWER a natural-language question in one call, under a strict byte budget (default 2048): ranked excerpts, linked neighbor notes (backlinks/outlinks) with one-line summaries, and follow-up source paths. Use search to locate notes and query_notes for metadata filters; use context_pack when you want answer-ready context without multiple round-trips. Empty excerpts with confidence "none" or "low" means the vault lacks coverage — do not infer content.
read_note
Read a note or a span of it — by heading section, block reference, or line range. Returns structured JSON with the content, bytes returned, total note size, and a contentHash to pass as prevHash to edit tools for compare-and-swap. Use search or outline_note first to find the right path and section names.
list_notes
List notes, optionally filtered by folder prefix or tag.
list_tags
List all tags in the vault with usage counts. Supports substring filtering, minimum count threshold, and sort order. Nested tags (e.g. area/work) include a parent field.
create_note
Create a new note at a vault-relative path. Optionally sets frontmatter and body content. Parent directories are created automatically. Fails if the note already exists unless overwrite is true (prevHash may guard the overwrite).
delete_note
Delete a note. By default it is moved to the vault .trash/ folder (recoverable by moving it back); pass permanent: true to remove it outright.
move_note
Move or rename a note to a new vault-relative path, rewriting wikilinks and markdown links in other notes that point at it so nothing breaks (links inside fenced code blocks are left alone). Parent directories at the destination are created automatically. Fails if the destination already exists unless overwrite is true.
rename_heading
Rename a heading in a note and rewrite every [[note#heading]] wikilink and embed across the vault so references keep working — aliases preserved, fenced code blocks left alone. Served from the warm backlink index, no vault scan. Heading matching is case-insensitive; with duplicate headings the first match wins, mirroring Obsidian link resolution.
append_note
Append text to a note body without touching the frontmatter. Safe for meeting notes, daily logs, and append-only workflows.
patch_frontmatter
Set, update, or delete frontmatter keys without reordering existing keys or changing quote style. Pass null as a value to delete a key.
outline_note
Return a note's structure — heading tree with offsets, block-reference anchors, and frontmatter key list — without returning any prose. Use this before section reads or patches to discover what sections exist at a fraction of the cost of reading the full note.
patch_note
Surgically edit a section of a note — targeted by heading or block reference — without rewriting the whole file. Operations: append (add after section), prepend (add after heading line), replace (swap section content). Frontmatter is never touched.
get_backlinks
Return every note that links to the target note, with the source line and an optional excerpt. Results come from the pre-built reverse-link index so this is a fast, pure index lookup. Sort order: source path ascending.
get_links
Return all outgoing wikilinks and embeds from a note. Each link is marked resolved (with target path) or unresolved. Duplicate targets are de-duplicated; results sorted by line number.
replace_in_note
Find and replace text within a note body. Supports literal and regex search, case sensitivity, whole-word matching, and a replacement limit. Frontmatter is never touched. Use dryRun to preview matches before writing.
get_periodic_note
Get the path and existence status of a periodic note (daily, weekly, monthly, quarterly, or yearly) for a given date. Reads folder/format config from .obsidian/daily-notes.json (daily) or the periodic-notes plugin data.json. Optionally creates the note from the configured template if it is missing.
append_periodic_note
Append text to a periodic note (daily, weekly, monthly, quarterly, or yearly). Preserves existing frontmatter exactly. Creates the note first (from template if configured) when createIfMissing is true (default).
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"seekstone obsidian mcp server": {
"seekstone": {
"command": "npx",
"args": [
"-y",
"seekstone"
],
"env": {
"SEEKSTONE_VAULT": "/absolute/path/to/your/obsidian/vault"
}
}
}
}
}McpServers
{
"seekstone": {
"command": "npx",
"args": [
"-y",
"seekstone"
],
"env": {
"SEEKSTONE_VAULT": "/absolute/path/to/your/obsidian/vault"
}
}
}The Obsidian MCP server that needs no plugin, no running Obsidian app — and doesn't blow your context window.
Filesystem-direct · single-digit-ms search · ~2 KB payloads · 19 tools · macOS · Linux · Windows
Same queries, same committed vaults, 20 runs each —full results across eight servers and three vault sizes below, fully reproducible from theharness.
Seekstone is an Obsidian MCP server— it gives Claude (and anyModel Context Protocolclient) 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 vaultdirectly from diskrather than routing through the Obsidian Local REST API plugin, and holds a warm full-text index in-process. The practical difference is twofold:
- Speed.Searches return insingle-digit millisecondswarm — up to~440× fasterthan 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 returnstens of megabytesand millions of tokens via a REST-proxy server returns~2 KBvia Seekstone — up to a~47,000× reductionthat only widens as your vault grows.
Search comes in two modes: rankedfull-text search(fuzzy and prefix matching), andstructured metadata queries—query_notesfilters 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 asseekstone— install withnpx -y seekstone. (Previously also published asobsidian-mcp-seekstone; that alias is deprecated but existing installs keep working.)
Most Obsidian MCP servers returnfull 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 — acrossthree vault sizes — 1,000 / 5,000 / 10,000 notes(20 runs each). Every number below isfully reproducible: 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 thatthis is where the architectures diverge— a real vault only grows.
Search payload — bytes returned per query (context tax; lower is better)
Seekstone staysflat (~2 KB)no matter how big your vault gets, because it always returns ranked excerpts — and it's now thesmallest 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-obsidianhits95 MBat 10k notes, and a single broad query (the capital of) peaked at370 MB / 97.8 million tokensin one tool call. At 10k notes that's a~47,000× context-tax difference.
Search latency — warm mean, ms (lower is better)
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 it stays insingle-digit millisecondseven at 10,000 notes. And the gapwidens with scale: from 1k → 10k notes the competitors slow down 5–10×, while Seekstone barely moves. Even thefastestalternative —obsidian-mcp-rs, which re-scans the vault on every query — is~6× slowerwarm at 10k notes with3× the payload, and the REST-proxy generation runs70–250× slower.
Seekstone is the only Obsidian MCP server that stays flat onbothpayload and latency as your vault grows— and the only one with published, reproducible benchmarks. The harness, the synthetic vaults, and the full results are open source: seebenchmark-scaling.mdand theharness. Clone, run, verify.
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 theseekstoneMCP server for this editor. Runnpx -y seekstone init --client code --write(usedesktop,cursor, orvscodefor 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 initis fully non-interactive — with--writeit validates the vault and patches the client config in one shot (Claude Code viaclaude mcp add, other clients via an additive JSON patch with a timestamped backup).
Option 1 — One-click (Claude Desktop, no terminal needed)
- Downloadseekstone.mcpbfromGitHub Releases
- Open it with Claude Desktop — double-click in Finder, or right-click → Open With → Claude Desktop
- 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.
Option 2 — Guided setup (recommended for CLI users)
OpenTerminal(macOS:Cmd+Space, type "Terminal", press Enter) and run:
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:
# 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 toclaude_desktop_config.json(Settings → Developer → Edit Config):
{ "mcpServers": { "seekstone": { "command": "npx", "args": Auto-detects your vault and configures Claude Code in one command:
npx -y seekstone init --client code --write
Or manually, if you prefer to specify the vault path explicitly:
claude mcp add seekstone --env SEEKSTONE_VAULT=/absolute/path/to/your/vault -- npx -y seekstone
Or let the CLI auto-detect your vault and patch~/.cursor/mcp.json(with a backup):
npx -y seekstone init --client cursor --write
Or add the block manually to~/.cursor/mcp.json(global) or<project>/.cursor/mcp.json(per-project):
{ "mcpServers": { "seekstone": { "command": "npx", "args": ["-y", "seekstone"], "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" } } } }
Or let the CLI auto-detect your vault and write the workspace config (.vscode/mcp.jsonin the current directory):
npx -y seekstone init --client vscode --write
code --add-mcp '{"name":"seekstone","command":"npx","args":["-y","seekstone"],"env":{"SEEKSTONE_VAULT":"/absolute/path/to/your/vault"}}'
Or add the block manually to.vscode/mcp.json(workspace) or via Command Palette →MCP: Open User Configuration(user-global). Note VS Code's two quirks: the top-level key isservers(notmcpServers), and"type": "stdio"is required:
{ "servers": { "seekstone": { "type": "stdio", "command": "npx", "args": ["-y", "seekstone"], "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" } } } }
Requires VS Code 1.102+; seekstone appears in Copilot Chat'sAgent modetools picker.
Seekstone is a standard MCP stdio server — any MCP client can run it. Use the same JSON block as above in your client's MCP config (command: npx,args: ["-y", "seekstone"], envSEEKSTONE_VAULT).
After installing, restart the client. On startup Seekstone walks the vault, builds an in-memory full-text index (a few seconds for thousands of notes), and keeps it live as you edit. The 19 tools below are then available to Claude.
RequiresNode.js≥ 22 for the CLI options. The one-click.mcpbbundle has no external requirements.
If Seekstone saves you context, consider⭐ starring the repo— it helps others find it.
Once Seekstone is connected, you can ask Claude things like:
- "Search my notes for everything about [topic] and give me a summary"— usessearch, returns ranked excerpts, not full files
- "Find all notes tagged #project and list their titles"— useslist_noteswith a tag filter
- "Read just the 'Decisions' section of my [project] note"— usesread_notewith a section selector, so only that slice enters context
- "What links to my [topic] note, and what does it link out to?"— usesget_backlinksandget_linksto walk your graph
- "Append today's standup notes to my daily note"— usesappend_periodic_note, resolving the daily-note path from your vault config (Obsidian doesn't need to be open)
- "Fix every occurrence of the old project name in this note"— usesreplace_in_note, with a dry-run preview before it writes
- "Add a summary section to the bottom of [note]"— usesappend_note, never touches frontmatter
- "Move all notes in /inbox to /archive/[year]"— usesmove_note
- "Update the status field in this note's frontmatter to 'done'"— usespatch_frontmatter, preserves key order and quote style
- "Create a new meeting note for today with a standard template"— usescreate_note
Claude never sees your full vault at once — it searches and reads selectively, so even large vaults (10k+ notes) stay within context budget.
Every write tool (append_note,patch_note,patch_frontmatter,replace_in_note,rename_heading,move_note,delete_note,append_periodic_note, andcreate_notewithoverwrite: true) supports optionalcompare-and-swap: pass thecontentHashyou got fromread_noteasprevHashand the call fails cleanly if the note changed underneath you — no silently discarded concurrent edit, no moving or deleting content you haven't seen. Every mutating result returns the newcontentHash, so chained edits need no re-reads.
Fastandcomplete.Seekstone is the only Obsidian MCP server in our benchmark set to implementlist_tags,outline_note,get_backlinks, andget_links— every other tested server supports only search, read, list, and write. Three more capabilities set it apart:
- Periodic notes, filesystem-direct.get_periodic_noteandappend_periodic_noteresolve daily, weekly, monthly, quarterly, and yearly note paths by reading your vault's own config (.obsidian/daily-notes.jsonand 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_frontmatteredits 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.
Seekstone walks the vault withfast-glob, parses each note's frontmatter (byte-aware, so writes can prove the frontmatter region is byte-identical pre- and post-write), and builds aMiniSearchfull-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 in Obsidian.
Writes are conservative by design:append_notenever touches frontmatter, andpatch_frontmatteredits 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 — seedocs/ARCHITECTURE.md.
Seekstone reads — and, via the write tools, modifies — files underSEEKSTONE_VAULTon your local disk. It makesno network callsand sendsno telemetry. Logs are metadata-only by default (note contents only appear atdebuglevel). Nothing is written outside the vault except an optional log file you configure.
Giving an AI write access to your notes deserves more than "trust us." Seekstone ships a named, tested contract —docs/WRITE-SAFETY.md— ofeight 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, and configurable write scoping / read-only mode. The same suite runs headlessly against other FS-direct servers — the comparison table is in the contract.
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 theModel Context Protocol(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 nine in the table above —create_note,append_note,patch_note,patch_frontmatter,replace_in_note,move_note,rename_heading,delete_note,append_periodic_note). It makes no network requests. The vault path is sandboxed — no tool can read or write outside it. And you can tighten it further:SEEKSTONE_READ_ONLY=1removes the write tools from the session entirely, andSEEKSTONE_WRITE_PATHSrestricts writes to the folders you allow (say, onlyjournal/). 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. The in-memory index is small (a few MB for a typical vault) and starts in a few seconds.
How doesseekstone initfind 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.mcpbfile?**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.
Contributions welcome. SeeCONTRIBUTING.mdfor guidelines, or jump straight in:
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
The server has a real build (tsup →dist/) and is published to npm. The harness is run from source viatsx. Releases are automated — seedocs/RELEASING.md.
The harness exists to reproduce the benchmark numbers that motivated the filesystem-direct design. The default reproduction path (fs/seekstonebackends 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.
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) andSEEKSTONE_REST_URL(defaults tohttps://127.0.0.1:27124).
Seekstone is free and open source. If it saves you context (and money), you canbuy me a coffee.
Fsext-MCP-Server(Typescript): A full-featured secure MCP server for local file system operations, with built-in image processing, OCR and media tools. Fully compliant with the official MCP specification, delivering standardized request/response schemas, large-file streaming I/O, multi-transport remote deployment, and robust text search & replace workflows for LLM agent integration.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
