@kestrin/mcp-server

MCP server for Kestrin — read, search, and navigate your knowledge graph from any MCP-compatible client.

Features

• Read & search notes via on-disk reads plus daemon-aware retrieval
• Graph and tag navigation through daemon-backed metadata queries
• Write with version history through the same daemon pipeline as the desktop app
• Version restore and write completion with daemon revision IDs and waitFor checkpoints
• Semantic helpers for related notes, link suggestions, and tag suggestions when local models are configured

Install

npm install -g @kestrin/mcp-server

Or run directly:

npx @kestrin/mcp-server

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kestrin": {
      "command": "npx",
      "args": ["@kestrin/mcp-server"]
    }
  }
}

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "kestrin": {
      "command": "npx",
      "args": ["@kestrin/mcp-server"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "kestrin": {
      "command": "npx",
      "args": ["@kestrin/mcp-server"]
    }
  }
}

CLI Options

kestrin-mcp [options]

  --verbose, -v        Log diagnostics to stderr
  --version            Show version
  --help, -h           Show help

Tools

| Tool | Description | Mode | | ---------------------- | ---------------------------------- | ------------ | | read_note | Read markdown content | Mixed | | write_note | Create/update with version history | Daemon | | patch_note | Find-and-replace edit | Daemon | | rename_note | Rename or move a note | Daemon | | delete_note | Delete a note | Daemon | | await_write | Wait for a write token checkpoint | Daemon | | list_note_versions | List available version IDs | Daemon | | restore_note_version | Restore a version by revision ID | Daemon | | list_directory | List vault files | Standalone | | search_notes | Daemon retrieval or FTS fallback | Mixed | | get_backlinks | Documents linking to a note | Daemon | | get_outlinks | Documents a note links to | Daemon | | get_graph_context | Backlinks + outlinks in one call | Daemon | | list_tags | List tags on a document | Daemon | | search_by_tag | Find documents by tag | Daemon | | find_related_notes | Semantic related-note lookup | Daemon+Model | | suggest_links | Semantic wiki-link suggestions | Daemon+Model | | suggest_tags | Semantic tag suggestions | Daemon+Model |

Resources

| URI | Description | | ---------------------- | -------------------------------------- | | kestrin://vault/info | Vault name, path, doc count, tag count | | kestrin://tags | All unique tags with counts | | kestrin://recent | Recently opened documents |

Canonical Paths

write_note returns a path field containing the actual vault-relative path where the file was saved. For new files, this will be a UUID directory (e.g. a1b2c3d4-.../my-note.md) to isolate version history per document — matching the Kestrin frontend convention.

Always use the returned path for subsequent operations (patch_note, delete_note, read_note). The originally requested flat path (e.g. my-note.md) will not resolve after the file has been placed in its UUID directory. Existing files keep their current path unchanged.

Modes

Standalone — Works without the Kestrin app for direct file reads, directory listing, and local SQLite-backed fallback search.

Daemon — Requires the Kestrin app and kestrin-daemon. Uses daemon RPC for reads, writes, graph/tag queries, version restore, and completion checkpoints.

Consistency Notes

• read_note prefers a daemon read when available and falls back to direct disk reads only when the app is not running.
• search_notes prefers daemon retrieval when available and falls back to local FTS metadata only in standalone mode.
• Graph, tag, version, and semantic tools are daemon-backed and require the app runtime to be available.
• Write and restore tools go through kestrin-daemon. A successful response always means the change was persisted on disk and version metadata was updated. Lexical indexing is guaranteed only when the call uses the default waitFor: "indexed" checkpoint; callers that opt into earlier checkpoints such as accepted or materialized may observe the write before search/tag/graph reads catch up.