Skip to content
Back to search

turbovault

Markdown and OFM SDK w/ MCP server that transforms your Obsidian vault into an intelligent knowledge system

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Epistates/turbovault with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Epistates/turbovault'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/epistates--turbovault/badge.svg)](/listings/epistates--turbovault)

HTML

<a href="/listings/epistates--turbovault"><img src="/api/listings/epistates--turbovault/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installation

**Prebuilt binaries**

Each [GitHub release](https://github.com/Epistates/turbovault/releases) has binaries for Linux, macOS and Windows built with every feature: all transports, SQL frontmatter queries, and the vector search plugin. Vector search stays off until you enable it with `--plugins vector_search` (or `TURBOVAULT_PLUGINS=vector_search`) and point it at a local model.

**From crates.io**

# Minimal install (7.0 MB, STDIO only - perfect for Claude Desktop)
cargo install turbovault

# With HTTP server (~8.2 MB)
cargo install turbovault --features http

# With all cross-platform transports (~8.8 MB)
# Includes: STDIO, HTTP, WebSocket, TCP (Unix sockets only on Unix/macOS/Linux)
cargo install turbovault --features full

# With SQL frontmatter queries (adds GlueSQL-powered query_frontmatter_sql tool)
cargo install turbovault --features sql

# Everything the prebuilt binaries have (add `unix` on Unix)
cargo install turbovault --features release

# Binary installed to: ~/.cargo/bin/turbovault

**From source:**

git clone https://github.com/epistates/turbovault.git
cd turbovault
just release
# Binary: ./target/release/turbovault

Option 1: Static Vault (Recommended for Single Vault)

turbovault --vault /path/to/your/vault --profile production

Then add to `~/.config/claude/claude_desktop_config.json`:

{
  "mcpServers": {
    "turbovault": {
      "command": "/path/to/turbovault",
      "args": ["--vault", "/path/to/your/vault", "--profile", "production"]
    }
  }
}

Option 2: Runtime Vault Addition (Recommended for Multiple Vaults)

Start the server without a vault:

turbovault --profile production

Then add vaults dynamically:

{
  "mcpServers": {
    "turbovault": {
      "command": "/path/to/turbovault",
      "args": ["--profile", "production"]
    }
  }
}

Once connected to Claude:

You: "Add my vault at ~/Documents/Notes"
Claude: [Calls add_vault("personal", "~/Documents/Notes")]

You: "Search for machine learning notes"
Claude: [Uses search() across the indexed vault]

You: "What are my most important notes?"
Claude: [Uses get_hub_notes() to find key concepts]

Atomic Git-Backed Writes

For vaults already managed by Git, enable the transactional backend in the TurboVault YAML config:

vaults:
  - name: personal
    path: ~/Documents/Notes
    is_default: true
    write_backend: git
    git:
      include_ignored: false
      require_commit_message: false

Start with `turbovault --config ~/.turbovault/config.yaml`. Every mutation is then a Git commit. Multi-operation batches build one isolated tree and advance the branch with compare-and-swap, so a stale path aborts the entire batch and concurrent TurboVault processes cannot interleave commit/materialization. The backend also refuses to overwrite dirty or untracked touched paths and refuses to reset an index containing staged changes.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 239 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # TurboVault
  2. [![Crates.io](https://img.shields.io/crates/v/turbovault.svg)](https://crates.io/crates/turbovault)
  3. [![Docs.rs](https://docs.rs/turbovault/badge.svg)](https://docs.rs/turbovault)
  4. [![License](https://img.shields.io/crates/l/turbovault.svg)](https://github.com/epistates/turbovault/blob/main/LICENSE)
  5. [![Rust 1.90+](https://img.shields.io/badge/rust-1.90%2B-orange.svg)](https://www.rust-lang.org/)
  6. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Epistates/turbovault)
  7. - MCP Registry name: `mcp-name: io.github.epistates/turbovault`
  8. TurboVault is an MCP server that gives AI agents safe, fast access to Obsidian vaults, and a set of Rust crates for working with Obsidian Flavored Markdown. It's a single binary with no runtime dependencies.
  9. - **Writes you can trust.** Every change goes through one write path: atomic renames with hash preconditions on a plain folder, or one Git commit per write (or per batch) on a Git-backed vault. Moving a note rewrites the wikilinks, Markdown links, reference links and canvas cards that point at it in the same change.
  10. - **An index that can't miss an edit.** Before serving search, graph or similarity results, TurboVault compares the vault against what it last indexed and applies what changed, so edits from Obsidian, a sync client or `git pull` are always seen, even on network and cloud-synced vaults where file watchers report nothing.
  11. - **Knowledge-aware tools.** Full-text search, link graph analysis, similarity, health scoring, Obsidian Bases, canvases, tasks and periodic notes, plus SQL over frontmatter.
  12. - **Built for agents.** Every tool has parameter descriptions, annotations, a typed output schema, paged results and errors that say what to do next. Notes are MCP resources you can subscribe to, and destructive calls ask the user first when the client supports it.
  13. - **Safe by default.** Vault registration is confined, protected folders (`.obsidian`, `.git`) are unreachable, and network transports require authentication.
  14. ## Install
  15. **Prebuilt binaries.** Each [GitHub release](https://github.com/Epistates/turbovault/releases) has archives for Linux (x86_64 and aarch64, glibc and musl), macOS (Intel and Apple silicon) and Windows (x86_64), built with every feature. Each archive has a `.sha256` file and a signed build provenance attestation:
  16. ```bash
  17. gh attestation verify turbovault-x86_64-unknown-linux-gnu.tar.gz --repo Epistates/turbovault
  18. ```
  19. **From crates.io:**
  20. ```bash
  21. cargo install turbovault # stdio only, all you need for Claude Desktop and Claude Code
  22. cargo install turbovault --features release # what the prebuilt binaries have
  23. ```
  24. Other features: `http`, `websocket`, `tcp`, `full` (all cross-platform transports), `unix`, `sql` (SQL over frontmatter) and `vector-search` (the vector search plugin).
  25. **Docker:** `ghcr.io/epistates/turbovault:<version>` (amd64 and arm64). Mount the vault at `/var/obsidian-vault`:
  26. ```bash
  27. docker run -i --rm -v "$HOME/Documents/Vault:/var/obsidian-vault" ghcr.io/epistates/turbovault:4.0.0
  28. ```
  29. **MCP Registry:** listed as `io.github.epistates/turbovault`, with cargo and OCI packages.
  30. ## Quick start
  31. **Claude Code:**
  32. ```bash
  33. claude mcp add turbovault -- turbovault --vault ~/Documents/Vault
  34. ```
  35. **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
  36. ```json
  37. {
  38. "mcpServers": {
  39. "turbovault": {
  40. "command": "/path/to/turbovault",
  41. "args": ["--vault", "/path/to/your/vault", "--profile", "production"]
  42. }
  43. }
  44. }
  45. ```
  46. Leave out `--vault` to start with no vault and let the agent register one with `add_vault`. Runtime-registered vaults are remembered across restarts. For several vaults, a Git backend or per-vault settings, use a config file: see [`config.example.yaml`](config.example.yaml) and the [configuration guide](docs/configuration/index.md).
  47. A good first call is `get_vault_context`: it returns the registered vaults, the active vault's counts and health, and the tools grouped by task.
  48. ## Tools
  49. `tools/list` shows the core tools by default. The ones marked *(advanced)* are callable by name all the same, and listed with `--show-advanced-tools` (see the [configuration guide](docs/configuration/index.md#tool-visibility)). Every tool that works inside a vault takes an optional `vault` argument naming the registered vault to run against; without it, the active vault. Coming from 3.x, [docs/migration/4.0.md](docs/migration/4.0.md) maps every old tool name to its replacement.
  50. ### Notes (9)
  51. - `get_vault_context`: Start here: vault status, health, the markdown dialect and the tools by task
  52. - `read_note`: Note content (whole, or by lines and sections) with the hash for conflict detection
  53. - `write_note`: Create, overwrite, append or prepend (auto-creates directories)
  54. - `edit_note`: Surgical edits via SEARCH/REPLACE blocks
  55. - `delete_note`: Delete a note, refusing while other notes link to it (or striking their links through)
  56. - `move_note`: Rename or relocate a note; Git-backed vaults atomically rewrite incoming wikilinks, Markdown links and canvas references
  57. - `get_notes_info`: Existence, size, modified time, chosen frontmatter values and tags for several notes at once
  58. - `move_file` *(advanced)*: Move or rename any file, such as an image or PDF
  59. - `diff_notes` *(advanced)*: Unified diff between two notes, or between a note and an audited version
  60. ### Batch & Git Fanout (3)
  61. - `batch_execute`: One all-or-nothing commit with `write_backend: git`; direct stays sequential
  62. - `fanout` *(advanced)*: `begin`, `commit` or `abandon` an isolated Git worktree for long or parallel work
  63. - `list_orphan_fanouts` *(advanced)*: Worktrees left behind by interrupted sessions
  64. ### Links & Graph (5)
  65. - `get_links`: A note's backlinks (`incoming`, canvases included) or outgoing links
  66. - `get_related_notes`: Multi-hop graph traversal
  67. - `graph_report`: One list about the graph: `hubs`, `centrality`, `dead_ends`, `isolated_clusters`, `cycles` or `broken_links`
  68. - `vault_health`: 0-100 health score with counts; `depth: full` adds dead-end and hub counts
  69. - `explain_vault`: Holistic overview of structure, health, hubs and next actions
  70. ### Search & Similarity (6)
  71. - `search`: BM25 search by keyword, narrowed by tags, frontmatter and folders, or `related_to` a note
  72. - `find_similar`: Notes about a topic or like a given note, by TF-IDF meaning rather than exact words
  73. - `query_metadata`: One frontmatter condition (`equals`, `contains`, `>`, `<`), with each match's frontmatter
  74. - `find_duplicates` *(advanced)*: Near-duplicate pairs across the vault
  75. - `compare_notes` *(advanced)*: How alike two notes are and how strongly the graph links them
  76. - `suggest_links` *(advanced)*: Notes a note could link to, with reasons
  77. ### Frontmatter & Tags (4)
  78. - `update_frontmatter`: Patch frontmatter fields (merge or replace)
  79. - `manage_tags`: Add or remove frontmatter tags
  80. - `inspect_frontmatter` *(advanced)*: Frontmatter as SQL columns (feature: `sql`)
  81. - `query_frontmatter_sql` *(advanced)*: Read-only SQL over frontmatter, tags and links via GlueSQL (feature: `sql`)
  82. ### Canvases, Bases, Tasks & Periodic Notes (5)
  83. - `read_canvas`: Read a `.canvas` (JSON Canvas 1.0): nodes, edges and the notes it points at
  84. - `write_canvas`: Create or replace a canvas, validated against the spec and written the way Obsidian writes it
  85. - `query_base`: Run a `.base` file's filters, formulas, sort, grouping and limit over the vault's notes
  86. - `query_tasks`: Find tasks by status, due and scheduled dates, tag, folder, priority and text (Tasks plugin emoji and Dataview fields)
  87. - `get_periodic_note`: Find or create the daily, weekly, monthly, quarterly or yearly note, using the vault's Daily notes or Periodic Notes settings
  88. ### Quality & Open Knowledge Format (8)
  89. - `validate_vault`: Problems Obsidian would trip on (pre-1.9 `tags`/`aliases`, bad frontmatter, broken links), by note and severity, for one note or the vault
  90. - `note_quality` *(advanced)*: Quality score for one note, or the vault-wide report
  91. - `find_stale_notes` *(advanced)*: Notes not modified within a threshold of days
  92. - `analyze_grounding` *(advanced)*: A note's claims and citations for an external judge, or the vault's uncited notes
  93. - `okf_validate` *(advanced)*: Validate the vault as an [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog) v0.1 bundle; usable as a CI gate
  94. - `generate_index` *(advanced)*: Generate or refresh `index.md` files for progressive disclosure (idempotent)
  95. - `append_log_entry` *(advanced)*: Append a dated entry to a folder's `log.md` (OKF section 7)
  96. - `visualize` *(advanced)*: Render the graph as a self-contained HTML file
  97. ### Templates & OFM (4)
  98. - `list_templates`: Available templates with their fields, or one by `template_id`
  99. - `create_from_template`: Render and write a templated note
  100. - `find_notes_from_template` *(advanced)*: Notes created from a template
  101. - `get_ofm_guide`: The Obsidian Flavored Markdown `quick_ref`, full `syntax` guide or an `example` note
  102. ### Vaults (4)
  103. - `list_vaults`: Registered vaults and the active one; with `name`, that vault's full configuration
  104. - `add_vault`: Register a vault folder at runtime, or `create: true` to create it first
  105. - `set_active_vault`: The vault tools use when a call names none
  106. - `remove_vault` *(advanced)*: Unregister a vault (its files are untouched)
  107. ### Audit & Export (4)
  108. - `audit_log` *(advanced)*: Change log with operation ids, or `summary: true` for statistics and the hash-chain check
  109. - `rollback_preview` *(advanced)*: What a rollback would change (read-only)
  110. - `rollback_note` *(advanced)*: Undo a change by operation id (audited, itself undoable)
  111. - `export` *(advanced)*: A `health`, `broken_links`, `stats` or `analysis` report as JSON or CSV
  112. ## Resources, prompts and confirmation
  113. - **Notes as resources.** Every note is `obsidian://note/{vault}/{path}`: listed, read as markdown, and subscribable. Subscribers hear when a note changes, whether TurboVault or another editor changed it.
  114. - **Prompts.** `triage_vault`, `repair_broken_links`, `review_period`, `summarize_note` and `ground_draft`, with completion for their arguments.
  115. - **Progress and cancellation.** Slow tools report progress, and a cancelled call stops before it writes anything.
  116. - **Confirmation.** `delete_note`, a `move_note` that replaces a note, a forced `rollback_note`, a `batch_execute` that deletes or replaces notes, and `add_vault` ask the user to confirm when the client supports elicitation. `--no-confirm-destructive` turns this off.
  117. ## Writes and Git
  118. On the default (direct) backend, each write is a temp file and an atomic rename, held to the note's `expected_hash` so an edit made since the last read is never lost. A batch applies in order and reports exactly what landed if it stops partway.
  119. On a Git-backed vault (`write_backend: git`), every write is one commit and every batch is one all-or-nothing commit, with compare-and-swap on the branch so concurrent processes can't interleave. TurboVault refuses to overwrite files with uncommitted changes, and if writing out a commit is interrupted, the next write or the next start finishes it. `fanout` gives an agent a private worktree for long or parallel work, merged back or thrown away as a unit.
  120. Every change is recorded in a hash-chained audit trail under `.turbovault/` (or as Git history), and `rollback_note` undoes one, refusing to discard a later edit unless forced.
  121. ## Security
  122. - **Vault registration is confined.** `add_vault` never accepts a filesystem root, the home directory, hidden or application-data directories under it, or system directories. `--allowed-vault-roots` limits it to chosen directories; on network transports it's off unless roots are set.
  123. - **Protected folders.** `.obsidian`, `.git`, `node_modules` and TurboVault's own `.turbovault` are unreachable through the note tools on both backends. A vault can protect more folders, never fewer.
  124. - **Network transports.** HTTP takes bearer tokens or OAuth JWTs (`--auth-mode`), with per-client rate limiting, and won't listen beyond loopback without authentication. WebSocket and TCP stay on loopback. The Unix socket lives in a private directory.
  125. - **Read-only.** `--profile read-only` refuses every mutating tool; `allowed_operations: read` makes one vault read-only.
  126. - **Bounds.** Files over 10 MiB (configurable) aren't read, written or scanned; every result count is capped; `query_frontmatter_sql` runs only `SELECT`, for at most 10 seconds and 1000 rows.
  127. - No shell execution anywhere.
  128. Report vulnerabilities through [GitHub private vulnerability reporting](SECURITY.md).
  129. ## Observability
  130. Logs go to stderr as JSON on stdio (`RUST_LOG` overrides the profile's level). `--otlp-endpoint` exports traces over OTLP, `--metrics-port` serves Prometheus metrics on 127.0.0.1, and every tool call is a span with the tool, vault, outcome and duration, never its arguments or note content.
  131. ## Performance
  132. Measured on synthetic vaults with a release build over MCP stdio:
  133. | | 10k notes | 50k notes |
  134. |---|---|---|
  135. | Startup | 0.5 s | 2.5 s |
  136. | Memory after startup | 213 MB | 0.93 GB |
  137. | `read_note` | 0.5 ms | 0.9 ms |
  138. | `search` (warm) | 3.5-8 ms | 3.5 ms |
  139. | Search after a restart | 61 ms | 258 ms |
  140. | `vault_health` | 1 ms | 16 ms |
  141. | `explain_vault` | 30 ms | 179 ms |
  142. | `write_note` | 14-31 ms | |
  143. The search index persists in TurboVault's cache directory, so a restart re-indexes only notes that changed.
  144. ## Obsidian Flavored Markdown
  145. Wikilinks (`[[note]]`, `[[note|alias]]`, `[[note#heading]]`, `[[note#^block]]`, and the table-escaped `\|`), embeds, Markdown links (inline, reference-style and percent-encoded), tags (`#tag`, `#parent/child`), tasks (including Tasks plugin emoji and Dataview fields), callouts, YAML frontmatter as Obsidian 1.9 reads it, properties with links, headings, JSON Canvas 1.0 and Bases.
  146. ## Use the crates
  147. | Crate | Purpose |
  148. |---|---|
  149. | [`turbovault-core`](crates/turbovault-core) | Models, configuration, errors, multi-vault management |
  150. | [`turbovault-parser`](crates/turbovault-parser) | Obsidian Flavored Markdown and JSON Canvas parsing |
  151. | [`turbovault-graph`](crates/turbovault-graph) | Link graph, health and centrality |
  152. | [`turbovault-vault`](crates/turbovault-vault) | `VaultManager`: the note cache, the freshness gate and the write path |
  153. | [`turbovault-git`](crates/turbovault-git) | The Git write substrate |
  154. | [`turbovault-audit`](crates/turbovault-audit) | Audit trail, snapshots, rollback |
  155. | [`turbovault-batch`](crates/turbovault-batch) | Batch operation types and validation |
  156. | [`turbovault-export`](crates/turbovault-export) | JSON and CSV reports |
  157. | [`turbovault-sql`](crates/turbovault-sql) | SQL over frontmatter (GlueSQL) |
  158. | [`turbovault-tools`](crates/turbovault-tools) | The logic behind the MCP tools |
  159. | [`turbovault-plugin-api`](crates/turbovault-plugin-api) | The contract for compiled-in plugins |
  160. | [`turbovault-vector`](crates/turbovault-vector) | Hybrid dense and BM25 search |
  161. | [`turbovault`](crates/turbovault) | The MCP server |
  162. ## Build from source
  163. ```bash
  164. git clone https://github.com/epistates/turbovault.git
  165. cd turbovault
  166. cargo build --release # ./target/release/turbovault
  167. cargo test --workspace --all-features
  168. ```
  169. Rust 1.90 builds the crates; the test suite needs 1.93.1 or later. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [development guide](docs/development/index.md).
  170. ## Migrating from 3.x
  171. 4.0 consolidates 79 tools into 52, adds the per-call `vault` argument and hides the advanced tools from `tools/list` by default. [docs/migration/4.0.md](docs/migration/4.0.md) maps every old tool and parameter to its replacement, and the [changelog](CHANGELOG.md) lists every library API change.
  172. ## License
  173. MIT. See [LICENSE](LICENSE).
  174. ## Links
  175. - [Documentation](docs/README.md)
  176. - [Changelog](CHANGELOG.md)
  177. - [Issues](https://github.com/epistates/turbovault/issues)
  178. - [TurboMCP](https://github.com/epistates/turbomcp), the framework TurboVault is built on
  179. - [Model Context Protocol](https://modelcontextprotocol.io)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.