cluefinch/mcp-server

**Deep Research infrastructure for AI agents.**
Cluefinch MCP gives AI agents a complete toolkit for working with the web through the Model Context Protocol (MCP).
With Cluefinch, an agent can search the web, read pages, navigate between related sources, and carry out in-depth research.
Cluefinch MCP can make the internet part of your AI agent's workspace — from finding a single fact to carrying out complex, multi-step research across multiple sources.
Cluefinch MCP is completely free to use and requires no paid subscription. It works with AI agents whether they are powered by local LLMs or cloud-based models, and does not require a commercial search API or a subscription to a cloud-hosted Deep Research service.
Cluefinch MCP does not impose its own limits on the number of search queries or research runs.
Your agent gets the tools it needs to work effectively with the web, while you retain control over how those tools are used. Cluefinch integrates easily with MCP-compatible AI tools and fits into the workflow you already use.
What Cluefinch MCP can do
Web Search
Cluefinch MCP lets an agent search the internet through your own SearXNG instance.
The agent can formulate and refine search queries, use different search engines, restrict searches by language or domain, and issue follow-up or revised queries when needed.
Web Reading
Once a useful link is found, the agent can open the page through Cluefinch MCP and receive cleaned text ready for model processing.
Large pages do not have to be loaded into the model's context all at once. The agent can read them in chunks, continue from a specific position, and request additional context only when it is actually needed.
Source Navigation
After finding a useful page, the agent can inspect its HTTP/HTTPS links and use the source's own structure to continue the research: move through documentation sections and report chapters, follow pagination, open related pages, and reach primary materials — without returning to a search engine at every step.
Deep Research
Cluefinch MCP gives the agent the tools to carry out multi-source research workflows.
The agent can pursue several lines of inquiry at once, work with both search results and known URLs, gather material from different sources, examine the most relevant parts of long documents, and deepen the investigation as new questions emerge.
The agent remains in control of the research process: it decides what to search for next, which sources deserve closer inspection, how to interpret the collected material, and when there is enough evidence to produce an answer.
The depth of the research — from a quick product lookup to complex, multi-stage analysis — depends on the task, the model, and the user's instructions.
Quick Start
Cluefinch MCP requires Python **3.12.4 or later**.
1. Install Cluefinch MCP
After installation, make sure the cluefinch executable is available through the PATH environment variable.
On Windows:
On macOS and Linux:
If cluefinch is not found, add the directory containing the installed executable to PATH.
2. Start SearXNG
Cluefinch uses SearXNG as its search backend. If you do not already have your own SearXNG instance, the repository includes a ready-to-use local configuration example:
- examples/searxng/compose.yaml
- examples/searxng/settings.yml
To run the example, you need Docker with Docker Compose support.
Download these files into a separate directory and create a .env file alongside them with a random SEARXNG_SECRET.
On macOS and Linux:
On Windows PowerShell:
Then start SearXNG with Docker Compose:
By default, the local SearXNG instance will be available at:
3. Connect Cluefinch MCP to your AI tool
Cluefinch connects easily to popular AI tools and runs as a standard local MCP server over stdio.
Ready-to-use connection examples are provided in the next section.
Integrating with AI tools
Cluefinch MCP uses the standard local MCP stdio transport, so in most clients you only need to specify the cluefinch command.
Below are minimal examples of integrating Cluefinch with some popular AI tools. Cluefinch can also be used with other clients that support local MCP servers over stdio.
The examples below use SearXNG at http://127.0.0.1:8081, as shown in the Quick Start section above.
If your SearXNG instance does not use the default address, pass MCP_SEARCH_SEARXNG_URL through the MCP server environment in your client's configuration.