mcp-retrieval

Both transports the MCP SDK supports are available and expose the identical tool set:

- stdio— the client launches the binary and talks over stdin/stdout (the default, ideal for desktop clients).
- http— a long-running streamable HTTP server (useful for remote/shared deployments).

All three are annotated asread-only. Each tool returns a structured JSON payload that matches its output schema; the SDK mirrors the same JSON into the text content block for clients that do not readstructuredContent.

Bothqueries/urlslists are capped atmax_queries(10) items per call. Queries must be ≤ 512 characters; URLs ≤ 2048 characters andhttp/httpsonly.

Every call fans out across the input list and returns one entry per query/URL, each with its ownstatus—success,failed, ortimeout— so a partial failure still returns the items that did work.

countis the number of items actually returned, and it can belower than the requestedmax_results/max_images: duplicates within a single query's results are removed before the limit is applied, and the upstream may simply have fewer items to give. A smallercountis a normal outcome, not an error.

Deduplication isper query, not across queries. Each entry is deduplicated on its own, so a link found by two of the queries in the same call appears in both entries — dedupe the union yourself if you need it.

Request-level failures are returned as a tool result withisError: trueand a plain-text message, not as a JSON-RPC error — the model reads the message and can correct the call itself. Per-item failures never do this; they stay inside the payload asstatus: "failed"/"timeout".

A call fails outright only when the input is rejected before any work starts, or wheneveryitem in it fails:

The all-failed messages deliberately do not distinguish timeouts from other causes: a mixed batch can fail for several reasons at once, and the per-itemstatusalready carries that detail whenever at least one item survives.

- web_scrapehandles HTML only.Pages are run through a readability extractor, which needs article markup, sotext/plainresponses yield nothing and come back asstatus: "failed". Raw-file hosts are the common case:raw.githubusercontent.com,github.com/.../raw/...,cdn.jsdelivr.net. Scrape the rendered page instead of the raw file.
- web_search_imagesrelevance is not guaranteed.For some queries Bing Images serves a page that is not a result set, and it is parsed as though it were — the tool then returns unrelated images withstatus: "success". Treat image results as best-effort and verify them before showing them to a user.
- No JavaScript.Pages are fetched as-is; content rendered client-side is invisible to the extractor.

Pick whichever fits — all of them give the identical server.

docker pull ghcr.io/role1776/mcp-retrieval:latest

go install github.com/Role1776/mcp-retrieval/app/cmd/mcp-retrieval@latest # needs Go 1.25.5+

Or build the binary in place (the Go module lives inapp/):

# defaults: stdio transport, no configuration needed ./bin/mcp-retrieval # with an explicit env file ./bin/mcp-retrieval -env /absolute/path/to/.env

Point your client at the built binary. Example Claude Desktop config:

{ "mcpServers": { "retrieval": { "command": "/absolute/path/to/mcp-retrieval", "env": { "MAX_RESULTS": "20" } } } }

Theenvblock is optional —"command"alone is enough.

Run the image on stdio. Configuration still travels through theenvblock, but Docker needs each variable named on the command line with-efor it to reach the process:

SetMCP_TRANSPORT=httpand the server listens onSERVER_PORTatMCP_PATH(defaulthttp://localhost:8080/mcp).

The version advertised to clients is not configurable: it is stamped into the binary at build time from the git tag.

When a proxy is configured, each outbound request gets a unique session id appended to the login, so the upstream provider rotates the exit IP per request.

Each value is checked on its own — it must be greater than zero — but theDEFAULT_,MIN_andMAX_triples arenotcross-checked against each other at startup. An inconsistent set does not stop the server; it is reconciled per request instead:

None of this needs configuration to work — the defaults above are applied automatically. Only proxy credentials are optional extras.

Everything Go lives inapp/, so either use the makefile from the repository root or pass-C appto the toolchain:

make build # compile the binary make test # run tests go -C app build ./... # compile everything go -C app test ./... # run tests go -C app vet ./... # static checks

Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.

A private, local research assistant that searches the web and scrapes content using DuckDuckGo.

Fetch, convert, and search AWS documentation pages, with recommendations for related content.

Search campgrounds around the world on campertunity, check availability, and provide booking links.

The Ferryhopper MCP Server exposes ferry routes, schedules and booking redirects so an AI assistant can discover connections across Europe and the Mediterranean and send users to Ferryhopper to complete bookings.

All-in-One SEO & Web Intelligence Toolkit API from FetchSERP.

MCP server that provides read-only access to HyperKitty, the web-based email archive component of Mailman 3.

At Sunrise Apps, we believe AI agents should be limitless, especially when it comes to visual data. We created ImageSorcery to bridge the critical gap in AI's ability to interact with and manipulate images directly, all while upholding the highest standards of privacy and security.

Just Domain is the domain registrar for businesses built with AI. Its remote MCP server checks availability and returns first-year and renewal pricing, plus a link to register on justdomain.ai, with DNS and WHOIS privacy in the same place. No account, no API key, read only. Endpoint: https://mcp.justdomain.ai/