MCP Retrieval

What MCP Retrieval does

MCP Retrieval MCP server provides three read-only tools for web retrieval: web_search, web_search_images, and web_scrape. The search tools accept multiple queries and process them in parallel. Web results are deduplicated and reranked within each query, while image results are returned per query. The scraping tool accepts multiple HTTP or HTTPS URLs and returns extracted page content as Markdown.

Web search uses DuckDuckGo Lite, and image search uses Bing Images. Page downloads pass through a readability extractor intended to isolate main article content. No API keys are required. Results use structured JSON, and the same JSON is also included as text for clients that do not consume MCP structured content.

How it works

Each request can contain up to 10 queries or URLs by default. A search query can be no longer than 512 characters, and a URL can be no longer than 2,048 characters. Search results default to five items per query; image search defaults to five images. These limits can be capped by server configuration.

A batch produces a separate result entry for each query or URL. Entries include success, failed, or timeout status, so a request can return useful items even when some upstream operations fail. Deduplication happens separately for each query, not across the complete batch. Search and image calls can also apply day, week, month, or year freshness filters.

Setup and configuration

MCP Retrieval MCP server can run over stdio or streamable HTTP. Stdio is intended for clients that launch the binary locally, while HTTP supports a long-running or shared deployment. Installation options include a container image, a prebuilt release archive, an MCP bundle, or a source build.

The source installation requires Go 1.25.5 or newer. The application can be installed with go install, or built from the repository with make build; the latter produces bin/mcp-retrieval. Container users can pull ghcr.io/role1776/mcp-retrieval:latest. The MCP bundle contains a platform-specific compiled binary and does not require Docker or Go.

Tools and capabilities

• web_search accepts required queries, optional max_results, timeout_ms, and a freshness date.
• web_search_images accepts required queries, optional max_images, timeout_ms, and date.
• web_scrape accepts required urls, plus robots_txt, timeout_ms, remove_links, and max_chars.

Scraping can honor a page's robots.txt, remove Markdown links, and truncate extracted text. Requests use five seconds as the default whole-call timeout, subject to configured minimum and maximum values. Multiple operations within a tool call run in parallel.

Limitations and notes

The scraper handles HTML pages, not raw text files or other non-HTML content. It depends on article-oriented markup, so raw-file hosts and responses with text/plain may produce failed results. It does not execute JavaScript, making client-rendered content unavailable to extraction.

Image relevance is best-effort. Bing Images can sometimes return a page that is not a proper result set, which may lead to unrelated images being reported as successful results. Verify images before presenting them to users.

Invalid input, excessive list sizes, malformed URLs, and empty queries produce request-level errors. Per-item failures remain inside the result payload when other work succeeds; a call fails outright when validation rejects the request or every item fails.