TurboVault

The ultimate Rust SDK and high-performance MCP server for Obsidian-flavored Markdown (.ofm) and standard .md vaults.

TurboVault is a dual-purpose toolkit designed for both developers and users. It provides a robust, modular Rust SDK for building applications that consume markdown directories, and a full-featured MCP server that works out of the box with Claude and other AI agents.

Two Ways to Use TurboVault

1. As a Rust SDK (For Developers)

Build your own applications, search engines, or custom MCP servers using our modular crates. TurboVault handles the heavy lifting of parsing .md and .ofm files, building knowledge graphs, and managing multi-vault environments.

Modular Architecture: Use only what you need (Parser, Graph, Search, etc.).
High Performance: Sub-100ms operations for most tasks.
Extensible: Easily build your own specialized MCP servers on top of our core logic.
SOTA Standards: Fully supports Obsidian-flavored Markdown (wikilinks, embeds, callouts).

2. As a Ready-to-Use MCP Server (For Users)

Transform your Obsidian vault into an intelligent knowledge system immediately. Connect TurboVault to Claude Desktop or any MCP-compatible client to gain 44 specialized tools for your notes.

Zero Coding Required: Install the binary and point it at your vault.
44+ Specialized Tools: Searching, link analysis, health checks, and more.
Multi-Vault Support: Switch between personal and work notes seamlessly at runtime.

Core Crates (The SDK)

TurboVault is a modular system composed of specialized crates. You can depend on individual components to build your own tools:

| Crate | Purpose | Docs | |-------|---------|------| | turbovault-core | Core models, MultiVault management & types | | | turbovault-parser | High-speed .md & .ofm parser | | | turbovault-graph | Link graph analysis & relationship discovery | | | turbovault-vault | Vault management, file I/O & atomic writes | | | turbovault-tools | 44+ MCP tool implementations | | | turbovault-batch | Atomic batch operations | | | turbovault-export | Export & reporting (JSON/CSV/MD) | | | turbovault | Main MCP server binary / SDK orchestrator | |

Why TurboVault?

Unlike basic note readers, TurboVault understands your vault's knowledge structure:

Full-text search across all notes with BM25 ranking
Link graph analysis to discover relationships, hubs, orphans, and cycles
Vault intelligence with health scoring and automated recommendations
Atomic batch operations for safe, transactional multi-file edits
Multi-vault support with instant context switching
Runtime vault addition — no vault required at startup, add them as needed

Powered by TurboMCP

TurboVault is built on TurboMCP, a Rust framework for building production-grade MCP servers. TurboMCP provides:

Type-safe tool definitions — Macro-driven MCP tool implementation
Standardized request/response handling — Consistent envelope format
Transport abstraction — HTTP, WebSocket, TCP, Unix sockets (configurable features)
Middleware support — Logging, metrics, error handling
Zero-copy streaming — Efficient large payload handling

This means TurboVault gets battle-tested reliability and extensibility out of the box. Want to add custom tools? TurboMCP's ergonomic macros make it straightforward.

Quick Start

Installation

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

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

From source:

git clone https://github.com/epistates/turbovault.git
cd turbovault
make 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]

What Can Claude Do?

Search & Discovery

You: "Find all notes about async Rust and show how they connect"
Claude: search() -> recommend_related() -> get_related_notes() -> explain relationships

Vault Intelligence

You: "What's the health of my vault? Any issues I should fix?"
Claude: quick_health_check() -> full_health_analysis() -> get_broken_links() -> generate fixes

Knowledge Graph Navigation

You: "What are my most important notes? Which ones are isolated?"
Claude: get_hub_notes() -> get_isolated_clusters() -> suggest connections

Structured Note Creation

You: "Create a project note for the TurboVault launch with status tracking"
Claude: list_templates() -> create_from_template() -> write auto-formatted note

Batch Content Operations

You: "Move my 'MLOps' note to 'AI/Operations' and update all links"
Claude: move_note() + batch operations -> atomic multi-file update

Link Suggestions

You: "Based on my vault, what notes should I link this to?"
Claude: suggest_links() -> get_link_strength() -> recommend cross-references

44 MCP Tools Organized by Category

File Operations (5)

read_note — Get note content with hash for conflict detection
write_note — Create/overwrite notes (auto-creates directories)
edit_note — Surgical edits via SEARCH/REPLACE blocks
delete_note — Safe deletion with link tracking
move_note — Rename/relocate with automatic wikilink updates

Link Analysis (6)

get_backlinks — All notes that link TO this note
get_forward_links — All notes this note links TO
get_related_notes — Multi-hop graph traversal (find non-obvious connections)
get_hub_notes — Top 10 most connected notes (key concepts)
get_dead_end_notes — Notes with incoming but no outgoing links
get_isolated_clusters — Disconnected subgraphs in your vault

Vault Health & Analysis (5)

quick_health_check — Fast 0-100 health score (<100ms)
full_health_analysis — Comprehensive vault audit with recommendations
get_broken_links — All links pointing to non-existent notes
detect_cycles — Circular reference chains (sometimes intentional)
explain_vault — Holistic overview replacing 5+ separate calls

Full-Text Search (5)

search — BM25-ranked search across all notes (<500ms on 100k notes)
advanced_search — Search with tag/metadata filters
recommend_related — ML-powered recommendations based on content similarity
find_notes_from_template — Find all notes using a specific template
query_metadata — Frontmatter pattern queries

Templates (4)

list_templates — Discover available templates
get_template — Template details and required fields
create_from_template — Render and write templated notes
get_ofm_examples — See all Obsidian Flavored Markdown features

Vault Lifecycle (7)

create_vault — Programmatically create a new vault
add_vault — Register and auto-initialize a vault at runtime
remove_vault — Unregister vault (safe, doesn't delete files)
list_vaults — All registered vaults with status
get_vault_config — Inspect vault settings
set_active_vault — Switch context between multiple vaults
get_active_vault — Current active vault

Advanced Features (12)

batch_execute — Atomic multi-file operations (all-or-nothing transactions)
export_health_report — Export vault health as JSON/CSV
export_broken_links — Export broken links with fix suggestions
export_vault_stats — Statistics and metrics

Turbovault

Install / Use

README