Cluefinch MCP

Cluefinch MCP

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

python -m pip install cluefinch

After installation, make sure the cluefinch executable is available through the PATH environment variable.

On Windows:

where.exe cluefinch

On macOS and Linux:

command -v cluefinch

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:

printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)" > .env

On Windows PowerShell:

$secret = -join ((1..64) | ForEach-Object { '{0:x}' -f (Get-Random -Maximum 16) })

"SEARXNG_SECRET=$secret" | Set-Content -Encoding ascii .env

Then start SearXNG with Docker Compose:

docker compose up -d

By default, the local SearXNG instance will be available at:

http://127.0.0.1:8081

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.

Cursor

Add Cluefinch to your project's .cursor/mcp.json or to Cursor's global MCP configuration:

{

"mcpServers": { "cluefinch": { "type": "stdio", "command": "cluefinch" } } }

After restarting the MCP connection, Cursor will discover the Cluefinch tools and can use them in agent tasks.

Claude Code

Cluefinch can be added with a single command:

claude mcp add --scope user cluefinch -- cluefinch

To verify the connection:

claude mcp list

Codex

Add Cluefinch with:

codex mcp add cluefinch -- cluefinch

To verify the connection:

codex mcp list

GitHub Copilot in VS Code

Add the local MCP server to .vscode/mcp.json:

{

"servers": { "cluefinch": { "type": "stdio", "command": "cluefinch" } } }

Cluefinch will then become available to GitHub Copilot in agent mode as a set of MCP tools.

OpenCode

Add Cluefinch to opencode.jsonc:

{

"$schema": "https://opencode.ai/config.json", "mcp": { "cluefinch": { "type": "local", "command": ["cluefinch"], "enabled": true } } }

Qwen Code

Add Cluefinch to ~/.qwen/settings.json for user-level configuration, or to .qwen/settings.json for a specific project:

{

"mcpServers": { "cluefinch": { "command": "cluefinch", "args": [] } } }

After restarting Qwen Code, you can verify the connection with the /mcp command.

OpenClaw

Add Cluefinch with:

openclaw mcp add cluefinch --command cluefinch

Or configure it manually in openclaw.json:

{

"mcp": { "servers": { "cluefinch": { "command": "cluefinch", "transport": "stdio" } } } }

To verify the connection:

openclaw mcp probe cluefinch

Hermes Agent

Add Cluefinch to the config.yaml file used by your active Hermes profile:

mcp_servers:

cluefinch: command: "cluefinch" args: []

Restart Hermes after saving the configuration.

Configuring agent behavior

The agent formulates search queries, selects sources, and manages the research process using the available Cluefinch MCP tools. You can define your own rules for that process through instructions in AGENTS.md or equivalent settings in your AI tool.

Those instructions can govern both ordinary searches and deep, multi-stage research, including how individual Cluefinch MCP tools should be used.

For example, you can ask the agent to begin with a research plan, run several refinement queries through web_search, use web_links to navigate chapters and related pages, prioritize primary sources, and read large documents incrementally with web_fetch.

For multi-source collection and initial filtering, the agent can use research_collect. Your instructions can also define rules for reusing already collected context, checking conflicting sources, limiting additional search iterations, and keeping factual evidence separate from interpretation.

The repository includes an AGENTS.md file with a ready-made example of this kind of Deep Research workflow. You can use it as a starting point, simplify it for quick research, or adapt it to your own tasks, model, and output requirements.

Cluefinch MCP tools

At the MCP level, Cluefinch exposes four complementary tools that take an agent from web search to reading specific sources and then to multi-source research.

web_search

web_search runs searches through the configured SearXNG instance and returns links to potentially useful sources.

The agent can control the number of results, choose search engines and language, use Safe Search, restrict the search to a particular domain, or exclude unwanted domains. Cluefinch also reports when one or more SearXNG engines fail to respond, so the agent does not mistake an incomplete result set for a complete one.

web_fetch

web_fetch reads web pages directly. Cluefinch downloads the HTML from the specified URL, extracts the main text, converts it to Markdown, and returns only the portion the agent needs.

The agent can first request a small preview of the page to judge whether the source is useful, then continue reading only if needed. A long document can be read incrementally from a chosen position. Cluefinch returns next_start and a ready-to-use continuation action, so the agent does not need to calculate the next position manually. Along with the content, it receives the metadata needed to continue navigating the same retained version of the extracted text safely.

web_links

web_links extracts navigational HTTP/HTTPS links from an HTML page and returns them in document order. It lets the agent inspect the structure of a source it has already found: documentation sections, report chapters, pagination, appendices, primary-source references, and related pages.

This is especially useful in Deep Research. After finding a strong source, the agent can inspect its structure, open only the relevant sections with web_fetch, and then collect material from several selected sources with research_collect. This reduces unnecessary searches, helps preserve research context, and enables deeper work with primary materials.

Relative links are resolved into absolute URLs using the document's base URL. Links can be filtered by origin when needed, and large link sets can be retrieved incrementally across multiple requests.

Cluefinch also versions each retained link set. If the page's navigation changes between requests, the agent will not continue from stale positions in an outdated list.

Extracting links does not make requests to their destinations. Full outbound safety validation is applied only if the agent later decides to fetch one of those URLs.

research_collect

research_collect is designed to work with multiple sources at once. You can provide several search queries, specific URLs, or both.

Cluefinch gathers available sources, deduplicates documents by their final URLs after redirects, and identifies the most relevant passages in long documents. Each selected passage remains an exact slice of the extracted text with stable coordinates, so the agent can return to it later and request additional context when needed.

Each source receives a stable source_id, while collection problems — such as an unreachable URL, a failed search, or a duplicate final document — are reported explicitly in gaps. The agent decides whether enough material has been collected and which sources d