Flywheel MCP Server

Ask your vault questions. What changed this week? Who's involved? What connects to what? Get answers in seconds, not minutes of searching.

⚠️ Node 24 is NOT supported. Use Node 18, 20, or 22 LTS. Node 24 causes 60-90 second compilation timeouts that break MCP connections. See Requirements for details.

See What's Possible

"What's overdue this week?" (Solo Consultant)

You manage 3 clients, 4 projects, $42K in invoices. Ask Claude "What's overdue?" and get your answer in 2 seconds:

Overdue Tasks (3):
- clients/acme.md: Follow up on proposal 📅 Jan 2
- projects/beta-api.md: Send status update 📅 Jan 3
- invoices/INV-042.md: Payment reminder 📅 Jan 3

How: Flywheel indexes your vault and finds overdue tasks instantly. No manual searching through files.

"What's blocking the propulsion system?" (Engineering Project)

You're managing a rocket startup with 100+ technical dependencies. Ask Claude and instantly see the critical path:

Blocked: Propulsion System
  └─ waiting on: Turbopump Test Results
     └─ waiting on: Supplier Delivery (delayed)
        └─ affects: Engine Hot Fire Results, Thrust Validation

How: Flywheel traces backlinks and dependencies through how your notes connect. See the critical path instantly.

"How does AlphaFold connect to my docking experiment?" (Research)

You have 1,000+ research notes. Ask Claude and discover hidden connections:

AlphaFold → Protein Structure Prediction
  ↓
  connects via: Machine Learning Methods
  ↓
  referenced in: Your Docking Protocol (notes/experiments/dock-001.md)
  ↓
  shared concept: Conformational Analysis

How: Fast full-text search finds mentions across thousands of notes in milliseconds. Then traces how concepts connect through your knowledge graph.

What This Gives You

Find Connections - Backlinks, forward links, hub notes, orphans—see how your notes connect Search Everything - Find any phrase across thousands of notes in milliseconds Auto-Wikilinks - "talked to Alex" → suggests [[Alex Chen]] automatically Works at Scale - Fast responses even with 100,000+ notes

How It Works

Flywheel indexes your vault on startup and keeps it in memory. Ask questions, trace connections, search content—all instant.

The Obsidian enhancement: Your vault gains a queryable layer. Ask "what links to this?" or "what did I write about X last month?" and get answers immediately.

Self-Building Graph

When you write, Flywheel suggests wikilinks you might have missed:

• "met with Alex about the API" → suggests [[Alex Chen]] and [[API Redesign]]
• Your graph grows naturally as you capture thoughts

Context Cloud (Configurable)

After each entry, Flywheel can suggest related concepts:

- 14:30 Call about migration timeline
  → [[Q2 2026]] [[Data Migration]] [[Acme Corp]]

These suggestions surface connections you might not have thought to make. Fully optional—disable per-tool or globally if you prefer minimal notes.

Built for Real Vaults

✅ 100k notes - Tested with massive vaults ✅ Instant responses - Queries complete in milliseconds ✅ Cross-platform - Ubuntu, Windows, macOS ✅ Read-only - Safe exploration, no risk to your notes

Requirements

• Node.js 18, 20, or 22 (Node 22 LTS recommended)
• ⚠️ Node 24 is NOT supported — causes connection timeouts (see below)

Why Not Node 24?

Node 24 lacks prebuilt binaries for better-sqlite3, requiring 60-90 second compilation that exceeds MCP connection timeouts. Use Node 22 LTS instead:

# Using nvm
nvm install 22 && nvm use 22

# Using n
n 22

# Verify
node --version  # Should show v22.x

# Clear npx cache and retry
rm -rf ~/.npm/_npx
claude mcp list

This is temporary—once better-sqlite3 publishes Node 24 prebuilts (tracking issue), the limitation will be resolved.

Installation

Via .mcp.json

Add to your project's .mcp.json (in your vault root). Zero-config if .mcp.json is in your vault—no PROJECT_PATH needed:

{
  "mcpServers": {
    "flywheel": {
      "command": "npx",
      "args": ["-y", "@velvetmonkey/flywheel-mcp"]
    }
  }
}

Note: Windows native requires "command": "cmd", "args": ["/c", "npx", "-y", "@velvetmonkey/flywheel-mcp"]

(details) (summary)(strong)Advanced: Pointing to a different vault(/strong)(/summary)

If .mcp.json is NOT in your vault, or you want to use a different vault, set PROJECT_PATH:

Choose config based on where Claude Code runs, NOT where your vault is stored.

(details) (summary)(strong)Linux / macOS(/strong)(/summary)

{
  "mcpServers": {
    "flywheel": {
      "command": "npx",
      "args": ["-y", "@velvetmonkey/flywheel-mcp"],
      "env": {
        "PROJECT_PATH": "/path/to/your/vault"
      }
    }
  }
}

(/details)

(details) (summary)(strong)WSL (Windows Subsystem for Linux)(/strong)(/summary)

⚠️ Common mistake: Your vault may be on C:\Users\... (Windows filesystem), but if Claude Code runs in WSL, this is Linux—use npx directly, not cmd /c.

{
  "mcpServers": {
    "flywheel": {
      "command": "npx",
      "args": ["-y", "@velvetmonkey/flywheel-mcp"],
      "env": {
        "PROJECT_PATH": "/mnt/c/Users/yourname/path/to/vault"
      }
    }
  }
}

(/details)

(details) (summary)(strong)Windows (native, not WSL)(/strong)(/summary)

{
  "mcpServers": {
    "flywheel": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@velvetmonkey/flywheel-mcp"],
      "env": {
        "PROJECT_PATH": "C:/Users/yourname/path/to/vault"
      }
    }
  }
}

(/details)

Detecting Your Platform

Check the environment info shown at the start of your Claude Code session:

| Platform: value | Use config | |-------------------|------------| | linux | Linux (or WSL if your path starts with /mnt/) | | win32 | Windows | | darwin | macOS |

(/details)

Via CLI

# Zero-config (run from vault directory)
claude mcp add flywheel -- npx -y @velvetmonkey/flywheel-mcp

# With explicit vault path
claude mcp add flywheel --env PROJECT_PATH=/path/to/vault -- npx -y @velvetmonkey/flywheel-mcp

# Windows (native) - with explicit path
claude mcp add flywheel --env PROJECT_PATH=C:/path/to/vault -- cmd /c npx -y @velvetmonkey/flywheel-mcp

Verify

claude mcp list  # Should show: flywheel ✓

Tools

Organized into specialized toolsets covering graph queries, full-text search, temporal analysis, schema inference, and more.

| Category | Examples | |----------|----------| | Graph | get_backlinks, get_forward_links, find_orphan_notes, find_hub_notes | | Wikilinks | suggest_wikilinks, find_broken_links | | Health | get_vault_stats, get_folder_structure | | Query | search_notes, get_recent_notes, get_stale_notes | | System | refresh_index, get_all_entities | | Primitives | list_notes, list_tags, list_folders, get_note_info | | Periodic | get_periodic_note |

Full tool reference → (51 specialized tools, organized by category)

What This Unlocks

See How Notes Connect

"How does X relate to Y?" answered instantly. Backlinks, forward links, dependency chains—relationships you forgot existed, surfaced in milliseconds.

Find Anything Fast

Search across your entire vault instantly. That note you wrote six months ago? Found in milliseconds, not minutes of clicking through folders.

Example: Searching 50,000 research notes for "machine learning bias"? Obsidian search: 45 seconds. Flywheel: under 100ms. 500× faster.

Build Your Graph as You Write

Auto-suggest wikilinks as you capture thoughts. "talked to Alex about the API" → suggests [[Alex Chen]] and [[API Redesign]]. Your knowledge graph grows naturally, without manual linking sessions.

Discover Hidden Patterns

Surface connections you didn't know existed. Find hub notes (your most connected ideas), orphan notes (isolated thoughts waiting to connect), and unexpected paths between concepts.

When to Use What

| Task | Tool Category | Example | |------|---------------|---------| | Find connections | Graph queries | "How does Project X relate to Team Y?" | | Search content | Full-text search (FTS5) | "Find all notes mentioning 'deadline'" | | Discover patterns | Schema queries | "What topics appear most in my vault?" | | Track activity | Temporal queries | "What changed this week?" | | Combine insights | Graph + FTS5 | "Find blocked projects, then search their content for 'risk'" |

Real-World Examples

Sarah (Researcher)

Challenge: Finding relevant papers in 10,000 research notes

Before: 45 seconds of Obsidian search, then manually reviewing results With Flywheel: Query returns structured results in under 100ms

The difference: Sarah asks "what have I written about machine learning bias?" and gets an instant answer. Then traces how it connects to her current experiment.

James (Fiction Writer)

Question: "Which characters appear in scenes with Emma?"

What Flywheel does:

1. Finds all backlinks to [[Emma]] (who references her)
2. Searches scene descriptions for co-occurrences
3. Shows the character relationship map

Before: Reading 50+ scene files manually With Flywheel: Answer in under a second

Maya (Product Manager)

Workflow: Writing sprint notes, mentions "payment API" and "checkout flow"

What Flywheel does:

• Notices unlinked mentions in her prose
• Suggests [[Payment System]] and [[Checkout 2.0]]
• Links build automatically as she captures thoughts

Result: Her knowledge graph grows while she works. Connections emerge without dedicated "linking sessions."

Voice-to-Vault Workflow

Zero-friction capture: Speak → Graph entry in 10 seconds

The stack:

Whisper → Telegram → OpenClaw → Claude Code → Flywheel-Crank → Your Vault
  ↓          ↓          ↓            ↓              ↓
Voice      Transcript  Intent    Interprets    Auto-wikilinks
memo                   detection                + markup

Example workflow:

1. 🎤 Voice memo via Telegram: "Spoke with Sarah about the Acme migration"
2. 📝 OpenClaw transcribes and detects intent
3. 🤖 Claude Code interprets context
4. ✍️ Flywheel-Crank writes with auto-wikilinks
5. 🔗 Result: - 14:30 Call with [[Sarah Mitchell]] at [[Acme Corp]] about [[Acme Data Migration]]

What Flywheel provides:

• Entity detection from voice transcripts
• Contextual wikilink suggestions (co-occurrence patterns)
• Graph updates in real-time
• Backlink population automatically

See full voice workflow demo →

Integration ecosystem guide →

Why Flywheel?

Enhances Obsidian's built-in search:

• ✅ Relationship queries (backlinks, forward links, unlinked mentions)
• ✅ Auto-wikilink suggestions as you write
• ✅ Works with Claude Code for conversational queries
• ✅ Scales to 100k+ notes

Obsidian-native design:

• ✅ Reads your existing vault (no export, no sync)
• ✅ Understands wikilinks, frontmatter, tags
• ✅ Zero setup—just point it at your vault folder
• ✅ Read-only—can't accidentally corrupt your notes

Configuration

| Environment Variable | Required | Default | Description | |---------------------|:--------:|---------|-------------| | PROJECT_PATH | No | cwd() | Path to markdown vault directory |

Zero-config: If PROJECT_PATH is not set, the server uses the current working directory. When .mcp.json is in your vault root, this means no configuration needed—it just works.

The server scans the vault on startup and builds an in-memory index. No database required.

Architecture

┌──────────┐        ┌────────────────────────────────┐
│          │        │           Flywheel             │
│  Vault   │  scan  │  ┌──────────────────────────┐  │
│  (.md)   │───────►│  │       VaultIndex         │  │
│          │        │  │  notes, backlinks,       │  │
└──────────┘        │  │  entities, tags          │  │
                    │  └────────────┬─────────────┘  │
                    │               ▼                │
                    │  ┌──────────────────────────┐  │
                    │  │       MCP Tools          │  │
                    │  └──────────────────────────┘  │
                    └───────────────┬────────────────┘
                                    │ MCP Protocol
                                    ▼
                            ┌──────────────┐
                            │ Claude Code  │
                            └──────────────┘

Design decisions:

• File-first: Parses markdown directly, no database
• Eager loading: Full index on startup (fine for (5000 notes)
• In-memory graph: <10ms query times
• Privacy by design: Returns structure/metadata, not content

Performance

| Vault Size | Index Build | Query Time | Memory | |------------|-------------|------------|--------| | 100 notes | <200ms | <10ms | ~20MB | | 500 notes | <500ms | <10ms | ~30MB | | 1,500 notes | <2s | <10ms | ~50MB | | 5,000 notes | <5s | <10ms | ~100MB |

Error Handling

| Situation | Behavior | |-----------|----------| | Malformed YAML | Skipped, file treated as content | | Binary files | Detected and skipped | | Empty files | Indexed with no links/tags | | Large files ()10MB) | Skipped with warning | | Missing files | Graceful degradation |

Development

# Install
npm install

# Run with vault
PROJECT_PATH=/path/to/vault npm run dev

# Build
npm run build

# Test
npm test

# Interactive inspector
npm run inspect

License

AGPL-3.0 — velvetmonkey

Links

• Flywheel — Main project
• Model Context Protocol
• Claude Code