Recoll 文档检索 MCP

Recoll_MCP

This is an MCP for Recoll, tested on Windows but it is python based so should work on windows or Linux, it is buggy and a work in progress, but currently it does return results and it works. (although i am not quite happy with it yet and it needs a lot of improvements.)

MCP config:

"recoll": {
  "command": "python",
  "args": [
    "C:/recoll_mcp/recoll_mcp.py"
  ]
}

you will have to install python recoll, this usually must be a manual install

pip install "C:\Program Files\Recoll\Share\dist\Recoll-1.43.1-cp310-cp310-win_amd64.whl" 

replace the .whl with your recoll version, it is inscluded with the recoll installer for multiple versions of python.

how is this different from other document processors? RAG processes documents slowly and indexing many documents can be painfully slow, its just not great unless you only have a couple documents. the solution? recoll! recoll indexes up to terabytes of documents with a reliable index that never needs reprocessing or embedding model specific vector databases.

the MCP requests search results from recoll and the LLM can process them to respond.

Tools

recoll_search(query, start=0, limit=20, include_content=True)

• query: Recoll query syntax search terms.
• start: 0-based offset for pagination.
• limit: 1-200. Defaults to 20, capped to 10 when include_content=True (the default) to keep extraction time and response size manageable.
• include_content: if True, includes document text (up to 3000 chars per doc). If False, returns metadata (title/path) only.

Returns query, start, limit (actual values used), count, total (estimated), results, warning.

recoll_debug(query="test", limit=10)

Diagnostic helper. Returns backend status (recollq_found, recoll_python_available, confdir), environment snippet, which lookup, a trial query_run, and native/WSL recollq -V checks.

it is not as efficient on the response side as RAG, but with large document libraries, i haven't found a single solution that was actually practical or reliable, let alone easy.

Troubleshooting

• Build the Recoll index first (recollindex). No index = no results, even if the MCP starts cleanly.
• Non-default index location: set RECOLL_CONFDIR env var for the MCP server. The Python API connects with that confdir, and the CLI fallback passes it as recollq -c <confdir>.
• Check backend status with the recoll_debug tool: recollq_found, recoll_python_available, confdir, which lookup, trial query_run, and recollq -V version checks.
• Logs: recoll_mcp.log next to recoll_mcp.py (1 MB rotating x3, falls back to stderr if unwritable). Set RECOLL_MCP_DEBUG=1 for verbose payloads.
• Timeouts: CLI calls use RECOLL_MCP_CLI_TIMEOUT (default 30s). Content extraction is 10s per doc, full search aborts with truncated=True + warning after 120s and returns partial results.
• CLI fallback uses parseable recollq -F "url title" -n <start>-<limit> (skips 2 header lines, base64-decodes fields), with a recollq -b -n <start>-<limit> bare-URL fallback. total is an estimate.

Example using qwen3-1.7b with 32k context:

Prompt:

create an in depth summary about beekeeping, think deeply and make multiple requests for citations

Response:

Thought for 17.32 seconds
recoll_search
Thought for 39.27 seconds
recoll_search
Thought for 40.44 seconds

In-Depth Summary of Beekeeping

Historical Context

Beekeeping has ancient roots, with practices dating back thousands of years across diverse cultures. The The Golden Insect Handbook (1984) outlines traditional methods using hive types like the Langstroth Hive and emphasizes manual techniques for managing colonies. These early approaches focused on basic tools such as hives, beeswax extraction devices, and natural pest control strategies.

Essential Equipment

Modern beekeeping relies on specialized equipment:

• Hive Types: The Observation Hive Handbook (2017) details hive designs like the Langstroth Hive for structured pollination.
• Tools: Tools such as beeswax extractors, smoker devices, and protective gear are critical for managing colonies without harming them.

Management Strategies

Effective management includes:

• Swarming Prevention: Techniques to prevent colony swarms (e.g., dividing established hives) from disrupting hive stability.
• Hygiene Practices: Regular inspections, cleaning of honeycombs, and maintaining optimal temperatures in the hive are vital for worker bee health.

Challenges

Beekeepers face significant challenges:

1. Pests & Diseases (e.g., Varroa mites): The From Where I Sit (1998) highlights threats like these, requiring integrated pest management strategies.
2. Climate Change: Fluctuating temperatures and weather patterns affect hive operations, as noted in the Tropical & Sub-Tropical Apiculture guide (1986).

Economic Importance

Beekeeping contributes to agriculture through pollination services:

• The The Bee Book (2016) emphasizes its role in crop production and food security.
• Honey harvesting, wax extraction, and bee products generate income for small-scale farmers globally.

Sustainable Practices

Modern practices focus on sustainability:

• Honey Extraction: Techniques like the solar wax melter from The Observation Hive Handbook reduce energy use.
• Conservation Efforts: The Beekeeping in Rural Development (1999) advocates for habitat preservation and reducing pesticide reliance to protect bee populations.

Conclusion

Beekeeping is a multifaceted practice with historical, ecological, and economic significance. Its success depends on balancing traditional wisdom with modern innovations, ensuring the survival of pollinators while supporting rural communities worldwide.

Citations:

1. The Golden Insect Handbook (1984) – Traditional beekeeping methods.
2. Observation Hive Handbook (2017) – Hives and hive management techniques.
3. From Where I Sit (1998) – Pest challenges in apiculture.
4. Tropical & Sub-Tropical Apiculture (1986) – Pollination benefits for crops.