Turbovault
Markdown and OFM SDK w/ MCP server that transforms your Obsidian vault into an intelligent knowledge system
Ask AI about Turbovault
Powered by Claude Β· Grounded in docs
I know everything about Turbovault. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 47 specialized tools for your notes.
- Zero Coding Required: Install the binary and point it at your vault.
- 47 Specialized Tools: Searching, link analysis, SQL frontmatter queries, 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 | 47 MCP tool implementations | |
| turbovault-sql | SQL frontmatter queries (GlueSQL) | |
| 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
# With SQL frontmatter queries (adds GlueSQL-powered query_frontmatter_sql tool)
cargo install turbovault --features sql
# 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
47 MCP Tools Organized by Category
File Operations (5)
read_noteβ Get note content with hash for conflict detectionwrite_noteβ Create/overwrite notes (auto-creates directories)edit_noteβ Surgical edits via SEARCH/REPLACE blocksdelete_noteβ Safe deletion with link trackingmove_noteβ Rename/relocate with automatic wikilink updates
Link Analysis (6)
get_backlinksβ All notes that link TO this noteget_forward_linksβ All notes this note links TOget_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 linksget_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 recommendationsget_broken_linksβ All links pointing to non-existent notesdetect_cyclesβ Circular reference chains (sometimes intentional)explain_vaultβ Holistic overview replacing 5+ separate calls
Full-Text Search (8)
searchβ BM25-ranked search across all notes (<500ms on 100k notes)advanced_searchβ Search with tag, frontmatter, path, and limit filterssearch_by_frontmatterβ Find notes by frontmatter key-value pairrecommend_relatedβ ML-powered recommendations based on content similarityfind_notes_from_templateβ Find all notes using a specific templatequery_metadataβ Frontmatter pattern queriesinspect_frontmatterβ Schema inspection for SQL queries (feature:sql)query_frontmatter_sqlβ Arbitrary SQL against frontmatter via GlueSQL (feature:sql)
Templates (4)
list_templatesβ Discover available templatesget_templateβ Template details and required fieldscreate_from_templateβ Render and write templated notesget_ofm_examplesβ See all Obsidian Flavored Markdown features
Vault Lifecycle (7)
create_vaultβ Programmatically create a new vaultadd_vaultβ Register and auto-initialize a vault at runtimeremove_vaultβ Unregister vault (safe, doesn't delete files)list_vaultsβ All registered vaults with statusget_vault_configβ Inspect vault settingsset_active_vaultβ Switch context between multiple vaultsget_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/CSVexport_broken_linksβ Export broken links with fix suggestionsexport_vault_statsβ Statistics and metrics exportexport_analysis_reportβ Complete audit trailget_metadata_valueβ Extract frontmatter values (dot notation support)suggest_linksβ AI-powered link suggestions for a noteget_link_strengthβ Connection strength between notes (0.0β1.0)get_centrality_rankingβ Graph centrality metrics (betweenness, closeness, eigenvector)get_ofm_syntax_guideβ Complete Obsidian Flavored Markdown referenceget_ofm_quick_refβ Quick OFM cheat sheetget_vault_contextβ Meta-tool: single call returns vault status, available tools, OFM guide
Real-World Workflows
Initialize Without a Vault
# Server starts with NO vault required
response = client.call("get_vault_context")
# Returns: "No vault registered. Call add_vault() to get started."
response = client.call("add_vault", {
"name": "personal",
"path": "~/Documents/Obsidian"
})
# Auto-initializes: scans files, builds link graph, indexes for search
Multi-Vault Workflow
# Add multiple vaults
client.call("add_vault", {"name": "work", "path": "/work/notes"})
client.call("add_vault", {"name": "personal", "path": "~/notes"})
# Switch context instantly
client.call("set_active_vault", {"name": "work"})
search_results = client.call("search", {"query": "Q4 goals"})
client.call("set_active_vault", {"name": "personal"})
recommendations = client.call("recommend_related", {"path": "AI/ML.md"})
Vault Maintenance & Repair
# Quick diagnostic
health = client.call("quick_health_check")
if health["data"]["score"] < 60:
# Deep analysis if needed
full_analysis = client.call("full_health_analysis")
# Find and fix issues
broken = client.call("get_broken_links")
# Process broken links...
# Atomic bulk repair
client.call("batch_execute", {
"operations": [
{"type": "DeleteNote", "path": "old/deprecated.md"},
{"type": "MoveNote", "from": "old/notes.md", "to": "new/notes.md"},
# ... more operations
]
})
# Verify improvement
client.call("explain_vault") # Holistic view
Content Discovery
# Find what matters
hubs = client.call("get_hub_notes") # Top concepts
orphans = client.call("get_dead_end_notes") # Incomplete topics
# Deep search
results = client.call("search", {"query": "machine learning"})
# Explore relationships
related = client.call("get_related_notes", {
"path": "AI/ML.md",
"max_hops": 3
})
# Get suggestions
suggestions = client.call("suggest_links", {"path": "AI/ML.md"})
Performance Profile
| Operation | Time | Notes |
|---|---|---|
read_note | <10ms | Instant with caching |
get_backlinks, get_forward_links | <50ms | Graph lookup |
write_note | <50ms | Includes graph update |
search (10k notes) | <100ms | Tantivy BM25 |
quick_health_check | <100ms | Heuristic score |
full_health_analysis | 1β5s | Exhaustive, use sparingly |
explain_vault | 1β5s | Aggregates 5+ analyses |
| Vault initialization | 100msβ5s | Depends on vault size |
Key insight: Fast operations (<100ms) for common tasks, slower operations (1β5s) for exhaustive analysis. Claude uses smart fallbacks.
Configuration Profiles
| Profile | Use Case |
|---|---|
development | Local dev with verbose logging |
production | Production with security auditing and optimized logging |
readonly | Read-only access for safe exploration |
high-performance | Large vaults (10k+ notes) with aggressive caching |
SDK and Server Implementation
TurboVault is designed for two primary audiences: developers building on top of the Rust SDK and users looking for a standalone MCP server.
As a Standalone MCP Server
The quickest way to get started is using the pre-built binary. It's fully self-contained and optimized for performance:
- Link-time optimization (LTO) for maximum speed
- Configurable transports (STDIO, HTTP, WebSocket, TCP)
- Zero external dependencies (just point it at your vault)
# Build the optimized binary
cargo build --release --features full
# Run it
./target/release/turbovault --vault /path/to/vault --profile production
As a Rust SDK (Library)
The core of TurboVault is a collection of modular crates. Use them to build your own search engines, knowledge management tools, or even your own specialized MCP servers.
// Use in your own Rust projects
use turbovault_core::MultiVaultManager;
use turbovault_vault::VaultManager;
use turbovault_tools::SearchEngine;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// 1. Initialize the MultiVault manager
let manager = MultiVaultManager::new();
// 2. Add and initialize a vault (scans files, builds graph)
manager.add_vault("notes", "/home/user/notes").await?;
// 3. Perform high-level operations
let vault = manager.get_vault("notes")?;
let results = vault.search("machine learning")?;
// 4. Use these components to build your own custom MCP server
// or integrate into existing Rust applications.
Ok(())
}
Each crate is published to crates.io, so you can depend on individual components or the full stack.
Architecture
Built as a modular Rust workspace:
turbovault-core β Core types, MultiVaultManager, configuration
turbovault-parser β OFM (Obsidian Flavored Markdown) parsing
turbovault-graph β Link graph analysis with petgraph
turbovault-vault β Vault operations, file I/O, atomic writes
turbovault-batch β Transactional batch operations
turbovault-export β JSON/CSV/Markdown export
turbovault-sql β SQL frontmatter queries (GlueSQL, feature-gated)
turbovault-tools β 47 MCP tool implementations
turbovault (binary) β CLI and MCP server entry point
All crates are published to crates.io for public use.
Obsidian Flavored Markdown (OFM) Support
TurboVault fully understands Obsidian's syntax:
- Wikilinks:
[[note]],[[note|alias]],[[note#section]],[[note#^block]] - Embeds:
![[image.png]],![[note]],![[note#section]] - Tags:
#tag,#parent/child/tag - Tasks:
- [ ] Task,- [x] Done - Callouts:
> [!type] Title - Frontmatter: YAML metadata with automatic parsing
- Headings: Hierarchical structure extraction
Security
- Path traversal protection β No access outside vault boundaries
- Type-safe deserialization β Rust's type system prevents injection
- Atomic writes β Temp file β atomic rename (never corrupts on failure)
- Hash-based conflict detection β
edit_notedetects concurrent modifications - File size limits β Default 5MB per file (configurable)
- No shell execution β Zero command injection risk
- Security auditing β Detailed logs in production mode
System Requirements
- Rust: 1.90.0 or later
- OS: Linux, macOS, Windows
- Memory: 100MB base + ~80MB per 10k notes
- Disk: Negligible (index is in-memory)
Building from Source
git clone https://github.com/epistates/turbovault.git
cd turbovault
# Development build
cargo build
# Production build (optimized)
cargo build --release
# Run tests
cargo test --all
Or use the Makefile:
make build # Debug build
make release # Production build
make test # Run tests
make clean # Clean build artifacts
Documentation
Examples
Example 1: Search-Driven Organization
You: "What topics do I have the most notes on?"
Claude:
1. get_hub_notes() -> [AI, Project Management, Rust, Python]
2. For each hub:
- get_related_notes() -> related topics
- get_backlinks() -> importance/connectivity
3. Report: "Your core topics are AI (23 notes) and Rust (18 notes)"
Example 2: Vault Health Improvement
You: "My vault feels disorganized. Help me improve it."
Claude:
1. quick_health_check() -> Health: 42/100
2. full_health_analysis() -> Issues: 12 broken links, 8 orphaned notes
3. get_broken_links() -> List of specific broken links
4. suggest_links() -> AI-powered link recommendations
5. batch_execute() -> Atomic fixes
6. explain_vault() -> New health: 78/100
Example 3: Template-Based Content Creation
You: "Create project notes for Q4 initiatives"
Claude:
1. list_templates() -> "project", "task", "meeting"
2. create_from_template("project", {
"title": "Q4 Planning",
"status": "In Progress",
"deadline": "2024-12-31"
})
3. Creates structured note with auto-formatting
4. Returns path for follow-up edits
Benchmarks
M1 MacBook Pro, 10k notes, production build:
- File read: <10ms
- File write: <20ms
- Simple search: <50ms
- Graph analysis: <200ms
- Vault initialization: ~500ms
- Memory usage: ~80MB
Roadmap
- Real-time vault watching (VaultWatcher framework ready)
- Cross-vault link resolution
- Encrypted vault support
- Collaborative locking
- WebSocket transport (beyond MCP stdio)
Contributing
Contributions welcome! Please ensure:
- All tests pass:
cargo test --all - Code formats:
cargo fmt --all - No clippy warnings:
cargo clippy --all -- -D warnings
License
MIT License - See LICENSE for details
Links
- Repository: https://github.com/epistates/turbovault
- Issues: https://github.com/epistates/turbovault/issues
- MCP Protocol: https://modelcontextprotocol.io
- Obsidian: https://obsidian.md
- Related: TurboMCP
Get started now: ./target/release/turbovault --profile production
