mcp-trove-crunchtools

Self-hosted local file indexing MCP server with semantic search. Index any local directory (pCloud ~/AutoSync/, rclone mounts, ~/Documents/, anything) and search over the contents using hybrid vector + keyword search.

Features

• Hybrid search — Combines semantic vector similarity with FTS5 keyword matching
• Multiple file formats — PDF, DOCX, Markdown, plain text, source code
• Local-first — No cloud services, no per-seat fees, your data stays on your machine
• Lightweight embeddings — Uses fastembed (ONNX runtime) instead of PyTorch (~22MB vs ~2GB)
• Incremental indexing — SHA-256 checksum-based change detection
• Background mode — --index CLI mode for systemd timer automation

Install

uvx (recommended)

uvx mcp-trove-crunchtools

pip

pip install mcp-trove-crunchtools

Container

podman run -v trove-data:/data -v ~/Documents:/docs:ro quay.io/crunchtools/mcp-trove

Claude Code Integration

claude mcp add mcp-trove-crunchtools -- uvx mcp-trove-crunchtools

Tools (10)

Search (2)

Index Management (3)

Status (5)

Environment Variables

Image and video captioning is off until TROVE_VISION_BACKEND is set. The openrouter backend reads OPENROUTER_API_KEY_FILE or OPENROUTER_API_KEY, handles video as well as images, and only routes to zero-retention providers. The default caption prompt is:

Generate a concise caption for this image suitable for search indexing. Include: what you see, location if identifiable, time of day, any readable text or signs.

Background Indexing

Set up a systemd timer to keep your index fresh:

TROVE_PATHS=~/Documents:~/AutoSync mcp-trove-crunchtools --index

An --index run is built to be left alone:

• Each file is stored in one transaction, so a run killed part way (OOM, reboot) leaves no half-indexed file behind.
• Before indexing, it runs PRAGMA quick_check, keeps a daily backup, marks runs abandoned for more than 12 hours as aborted, and probes TROVE_REQUIRE_MOUNT.
• A path aborts instead of indexing when its file count falls below half of its last completed run (an unmounted source looks like deleted files), or when extractions keep timing out (a hung source). trove_reindex on the path overrides the file-count check.
• The exit code is 0 only when every path completed with no more than 10% of its files failing. Any other outcome exits 1, so the systemd unit fails visibly. TROVE_STATUS_FILE records what happened, path by path.
• The database records its embedding model and refuses to open under a different one, because vectors from two models cannot be searched together.
• Vision captions are cached by file content (SHA-256) and vision model, so a renamed or copied photo reuses its caption. A cached caption is kept while its content is indexed and for 90 days after. A file that failed permanently, or 5 times transiently, is not retried until it changes; trove_reindex on its path retries it.
• With TROVE_VISION_PDF_SCANS=true, a PDF whose first 5 pages hold under 20 characters of text (a scan) has its first page captioned through the vision backend, under the same budget and cache. It is off by default because it sends an image of the page to the vision provider.
• trove_reindex with no path re-reads every file, so it requires force=true. Cached captions are reused unless TROVE_VISION_MODEL changed.

License

AGPL-3.0-or-later