# shaqmughal/seekstone [Health: Active]

**Category:** 🛠️ Other Tools and Integrations  
**Repository:** https://github.com/shaqmughal/seekstone  
**GitHub Stars:** 35  
**npm Downloads (last month):** 3863  
**Views:** 1  
**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. Scopable by `folder`/`tag` and takes…
- **read_note** — Read the full content of a note by vault-relative path. Supports returning a single section, block, or line range.
- **read_notes** — Read up to 20 notes (or sections, blocks, line ranges) in one call under a total byte budget (default 16 KB). Over budget, each note is cut to a fair share and marked `truncated`; one bad path returns its own error without failing the batch.
- **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).
- **list_tasks** — List Markdown checkbox tasks as compact structured rows (path, line, state, text, nearest heading) — vault-wide or filtered by note, folder, tag, state, or modified time. Custom markers (`- [/]`, `- [-]`, …) are first-class single-char states.
- **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.
- **resolve_note** — Turn a note name, path, or frontmatter alias into its canonical vault path(s) — with provenance per match, all candidates when ambiguous, and did-you-mean suggestions when nothing matches.
- **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.
- **update_task** — Set one checkbox's state by path + line (from `list_tasks`) — rewrites exactly one character, leaving every other byte untouched. An `expectText` guard refuses if the task text changed since it was listed.
- **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"],
    "env": {
      "SEEKSTONE_VAULT": "",
      "SEEKSTONE_SEMANTIC": ""
    }
  }
}
```

**Requires environment variables:** `SEEKSTONE_VAULT`, `SEEKSTONE_SEMANTIC` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What shaqmughal/seekstone does

shaqmughal/seekstone exposes an Obsidian vault through MCP while reading the vault directly from its filesystem. Obsidian does not need to be running, and the Local REST API plugin is not required. The server is intended for MCP clients that need to search, inspect, organize, or edit Markdown notes without sending vault data to an external service.

Search returns ranked excerpts rather than complete notes, with an excerpt length of about 120 characters by default. Full-text search supports fuzzy and prefix matching. An optional semantic mode uses a local embedding model; hybrid mode combines meaning-based and keyword search. The model is downloaded once and runs locally afterward.

## How it works

Install the npm package with `npx -y seekstone` and point `SEEKSTONE_VAULT` at the vault's absolute path. Seekstone maintains an in-process index for keyword search and reads note files directly. Queries can be scoped by folders or tags and can impose byte budgets, so broad searches and multi-note reads return bounded results.

`context_pack` combines ranked excerpts, linked neighbor notes, short summaries, and follow-up paths for a question-oriented response. For more controlled workflows, an agent can resolve a note path, inspect its outline, read a section or block, and then follow backlinks or outgoing links.

## Setup and configuration

Run the package through a standard MCP stdio configuration:

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

Node.js 22.22 or newer is required. Set `SEEKSTONE_SEMANTIC=1` to enable semantic and hybrid search. Semantic search uses a local embedding model and requires a one-time download of approximately 30 MB. The package also has an older `obsidian-mcp-seekstone` npm name, while `seekstone` is the primary command.

## Tools and capabilities

- Search notes with ranked excerpts, fuzzy matching, prefix matching, and optional semantic modes.
- Query frontmatter, tags, folders, modification times, and file sizes with comparison predicates and selectable fields.
- Read one note or batches of up to 20 notes, with section, block, line-range, and total-byte controls.
- Navigate with note outlines, aliases, canonical path resolution, backlinks, outgoing links, tags, and periodic notes.
- List Markdown tasks with filters and custom checkbox states, then update one task with a text guard.
- Create, append, patch, replace, move, rename, and delete notes; link references are rewritten for supported moves and heading renames.
- Review journaled writes and undo a write back to the byte-identical previous state, including multi-file operations.

## Limitations and notes

Search and context tools are designed to return compact results; use `read_note` or `read_notes` when complete content is needed. Batch reads are capped at 20 notes and a default total budget of 16 KB, while `context_pack` defaults to 2 KB. Deletes move notes to the vault's `.trash/` folder unless permanent deletion is requested. The server supports macOS, Linux, and Windows.

_Full upstream README: https://allmcps.com/mcp/shaqmughal-seekstone/readme_