A
licenseNot graded
qualityC
maintenanceA stateless MCP server that provides web search, single page reading, and batch page reading tools, with automatic failover across multiple search and content extraction providers.
MIT
mcp-retriever
by keiranhaax
Allows using Brave as a search provider for web search, enabling queries to be fused with other providers and results deduplicated.
Allows using GitHub as a search provider for web search, enabling GitHub-sourced results to be included in fused search queries.
Allows using a SearXNG instance as a search provider for web search, supporting self-hosted or configured SearXNG deployments.
mcp-retriever
One MCP server for web search, page extraction, and cited research. Use your own providers, combine their results, and keep API keys out of client configs.
Search together: query two or three providers, deduplicate URLs, and merge rankings with
web_search_fused.Read more: extract pages, crawl sites, and recover 404/410 pages from Wayback Machine snapshots when archive fallback is enabled.
Control usage: optional spending caps for provider-reported usage, cooldowns, and paged access to large results.
Supports Tavily, Brave, Exa, You.com, SearXNG, GitHub, Linkup, Firecrawl, and Context.dev. Configure only what you use.
Context.dev covers web search, researched answers through ai_search,
news search with context_news, scraping, and brand tools. Its
highlights are available in the search and read tools. Exa search adds
a lite type, and Firecrawl search categories are developer, gov,
research, and pdf. See
Configuration
for details verified on 2026-10-19.
Quickstart
Requires Node.js 22+ and a provider key, or your own SearXNG instance.
npx -y mcp-retriever setupChoose providers, save keys privately, and connect your MCP client. The wizard writes Claude Desktop and Cursor entries, or shows the command/configuration for Claude Code and Codex. Billable key checks require consent.
Keys are stored in ~/.config/mcp-retriever/credentials.env, not in
client configs. Restart your client after setup.
Add, test, or remove keys:
npx mcp-retriever keys
Screenshots show a demo session with fixture credentials and a mocked key-check response, not a live provider validation.
Related MCP server: Web Search MCP
Example
Call web_search_fused with two configured search providers:
{
"query": "reciprocal rank fusion hybrid search",
"providers": ["brave", "exa"],
"limit": 3
}Results include source providers and merged rankings. If a provider fails, available results are returned with per-provider status.
Documentation
Configuration: keys, manual client setup, providers, and spending controls.
Search and read: retrieving pages and handling large results.
Tool groups: choose which capabilities to expose.
Deployment: remote HTTP access and operations.
Contributing: build from source and run checks.
Each server instance shares one trust boundary. Do not use its result store for mutually untrusted clients. Spending caps depend on provider-reported usage, not estimated costs.
License and origins
MIT.
Formerly named mcp-omnisearch; a maintained fork of Scott Spence's
mcp-omnisearch. When
upgrading this fork, rename OMNISEARCH_* settings to RETRIEVER_*,
omnisearch:// resources to retriever://, and _meta.omnisearch to
_meta.retriever. Preserve the old result store and spending ledger
when moving to ~/.cache/mcp-retriever/results; Docker/MCPO clients
must also change /omnisearch to /retriever.
Available Tools
1 toolresult_readRead up to 12000 UTF-8 bytes by opaque result_id. Follow next_offset and next_byte_offset as byte_offset within that line. Join byte continuations directly, ordinary line pages with LF. Results expire or may be evicted.BRead-onlyIdempotent
Read up to 12000 UTF-8 bytes by opaque result_id. Follow next_offset and next_byte_offset as byte_offset within that line. Join byte continuations directly, ordinary line pages with LF. Results expire or may be evicted.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum lines to return (default: 200, max: 500) | |
| offset | No | One-based line offset (default: 1) | |
| result_id | Yes | Opaque result ID returned by an Retriever tool | |
| byte_offset | No | UTF-8 byte offset within the selected line; pass next_byte_offset unchanged (default: 0) |
TDQS
B3.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, idempotent, read-only operation. The description adds useful behavioral context beyond that: results may expire or be evicted, pagination uses next_offset and next_byte_offset, and byte continuations must be joined directly while ordinary line pages use LF. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loads the byte limit and result_id requirement. The pagination sentences are dense and somewhat cryptic, especially 'ordinary line pages with LF', but no sentence is obviously wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries more burden. It covers the byte cap, pagination tokens, continuation joining, and expiry/eviction, but it does not fully describe the response shape or error behavior when a result has expired.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining how next_offset and next_byte_offset should be reused as byte_offset and how byte continuations versus line pages should be rejoined, which is important for correct parameter use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tautological: description restates name/title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the required opaque result_id and gives pagination follow-through instructions, but it never explicitly says when to use this tool versus another tool or what precondition produces a result_id. The schema mentions a Retriever tool, but the description itself does not route the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v0.0.25- First observed
result_read
TDQS
B3.4/5.0
Scored across 1 tool
Disambiguation5/5
There is only one tool, so there is no risk of confusing it with another operation. Its purpose—reading stored result content by an opaque result_id—is clear.
Naming Consistency4/5
With a single tool, there is no internal inconsistency across names. The name result_read is readable but uses a noun-first form rather than the more typical verb_noun convention.
Tool Count3/5
A single tool is borderline thin for a server surface, though this may be acceptable for a narrowly scoped result-retrieval utility. It does not feel excessive, but it lacks enough breadth to feel fully well-scoped.
Completeness3/5
The tool covers paginated reading of result content, including byte-offset continuation. However, there are no operations for discovering result IDs, inspecting metadata/status, or managing expired/evicted results, which are notable gaps for a retrieval surface.
Maintenance
ActivityMaintained
ResponsivenessSyncing
Related MCP Connectors
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Academic research MCP server for paper search, citation checks, graphs, and deep research.
Web search API and MCP server for developers building AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceMulti-source web search MCP server with RRF fusion, 4-layer URL extraction, and provider health tracking.68 npmMIT
- AlicenseAqualityDmaintenanceA unified MCP server for academic paper discovery, citation exploration, and research intelligence workflows over multiple scientific knowledge sources.71MIT
- FlicenseAqualityBmaintenanceMCP server for querying a page-citable research knowledge base built from PDFs, with exact filename and page citations.61-