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) | Directories to index in background mode, separated by : (; on Windows) |
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_PDF_MAX_PAGES |
5 |
Pages indexed from the start of each PDF, enough to tell what the document is about while keeping memory flat on large manuals; 0 or negative indexes every page |
TROVE_MAX_TEXT_CHARS |
5000000 |
Characters of extracted text kept per file; the rest is dropped with a warning so one huge document cannot flood a batch with chunks; must be positive, other values fall back to the default with a warning |
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
Metadata
1 maintainer
Release files for mcp-trove-crunchtools 0.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| mcp_trove_crunchtools-0.9.1.tar.gz | 245.5 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mcp_trove_crunchtools-0.9.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 288.6 kB
Release files / mcp_trove_crunchtools-0.9.1.tar.gz
| Download URL | mcp_trove_crunchtools-0.9.1.tar.gz |
|---|---|
| Size | 245.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fc2d0d634bbacdb8856bb82ab5bd8c7b1ddabd74d0e1ce97a8839dd5674fd95c
|
|
BLAKE2b-256 checksum How to use checksums |
c3ff49c1c1145da99ea09f120dba80578f819e82d7510cffa31832853ec70abb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 24, 2026.
Transparency logRelease files / mcp_trove_crunchtools-0.9.1-py3-none-any.whl
| Download URL | mcp_trove_crunchtools-0.9.1-py3-none-any.whl |
|---|---|
| Size | 43.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
947a4bbb612f53333cb1ae22601d89b60702af7166c5a820f12b7e923b2dce8e
|
|
BLAKE2b-256 checksum How to use checksums |
0938a4b070a7cb7bd71e725dcd4b97b4d1880d02e50191c45c91205bbdd59761
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 24, 2026.
Transparency logSecurity for mcp-trove-crunchtools 0.9.1
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for mcp_trove_crunchtools-0.9.1.tar.gz
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 Oct 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
