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 —
--indexCLI 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)
| Tool | Description |
|---|---|
trove_search |
Hybrid semantic + FTS5 search. Returns ranked chunks with file paths, scores, and content. |
trove_similar |
Find files similar to a given indexed file using its average embedding. |
Index Management (3)
| Tool | Description |
|---|---|
trove_index |
Index a specific file or directory. Skips unchanged files (checksum-based). |
trove_reindex |
Force re-index ignoring checksums. If no path given, reindexes everything. |
trove_remove |
Remove a file or directory from the index. |
Status (5)
| Tool | Description |
|---|---|
trove_status |
Index statistics: total files, chunks, disk usage, model info. |
trove_list |
List indexed files with metadata (size, type, chunk count). |
trove_get_chunks |
Show the text chunks for a specific indexed file. |
trove_log |
Activity log of indexing runs: start/finish times, file counts, errors. Persisted in SQLite, survives container crashes. |
trove_quality |
Per-file error tracking from indexing runs: which files failed, why, and whether a later index resolved it. |
Environment Variables
| Variable | Default | Description |
|---|---|---|
TROVE_DB |
~/.local/share/mcp-trove/trove.db |
SQLite database path |
TROVE_PATHS |
(none) | Colon-separated directories to index in background mode |
TROVE_INDEX_WORKERS |
20 |
Concurrent embedding workers |
TROVE_INDEX_BATCH |
50 |
Files per indexing batch |
TROVE_EMBEDDING_MODEL |
BAAI/bge-small-en-v1.5 |
fastembed model name |
TROVE_EXCLUDE_PATTERNS |
*.iso,*.zip,... |
Glob patterns to skip |
TROVE_CHUNK_SIZE |
1000 |
Characters per text chunk |
TROVE_CHUNK_OVERLAP |
200 |
Overlap between chunks |
TROVE_VISION_BACKEND |
none |
Vision captioning backend: gemini, openai, openrouter, ollama, or none to disable |
TROVE_VISION_MODEL |
per backend | Vision model. Defaults to gemini-2.5-flash, gpt-4o-mini, google/gemini-3.1-flash-lite (openrouter) or llava depending on the backend; empty when disabled |
TROVE_VISION_PROMPT |
(see below) | Caption prompt sent with each image |
TROVE_VISION_TIMEOUT |
120 |
Seconds allowed per vision API call |
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
License
AGPL-3.0-or-later
1 maintainer
Release files for mcp-trove-crunchtools 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mcp_trove_crunchtools-0.6.0.tar.gz | 236.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mcp_trove_crunchtools-0.6.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 277.1 kB
Release files / mcp_trove_crunchtools-0.6.0.tar.gz
| Download URL | mcp_trove_crunchtools-0.6.0.tar.gz |
|---|---|
| Size | 236.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
13417b974a2a4addf31207fdae970f7bb16ee051888f348973a29fb1913e98c0
|
|
BLAKE2b-256 checksum How to use checksums |
c87db5cf28eb9c2f2ab64f2141ae55c4e131cb90897b61e3ea3513bfb7c36c29
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / mcp_trove_crunchtools-0.6.0-py3-none-any.whl
| Download URL | mcp_trove_crunchtools-0.6.0-py3-none-any.whl |
|---|---|
| Size | 40.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fbd8cdb0773d701d142f8dfedbc7c4a9106db3097b05d7e08a0e12ed422256f4
|
|
BLAKE2b-256 checksum How to use checksums |
d6081b8b475d2013007131b14053b81ebece4e706185132f737cb7de53561566
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency log
