Server 01

v0.1.7

mcp-retrieval

Web search for your LLM, without an API key.

Search the open web from any MCP client without signing up for a search API. Queries go through DuckDuckGo Lite, images through Bing Images, and pages come back as readability-extracted Markdown rather than raw HTML.

Language: Go 1.25+
Transports: stdio, http
Licence: MIT
Registry: listed

Install

Four ways to get the binary

Pick whichever fits how you already install things. All four end with the same executable.

bash

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

No Go toolchain needed.

bash

go install github.com/Role1776/mcp-retrieval/app/cmd/mcp-retrieval@latest

Needs Go 1.25.5+.

bash

# Download mcp-retrieval_<version>_<os>_<arch>.mcpb from the latest
# release and open it with your client.

For clients that install .mcpb files. The bundle carries the compiled binary, so it needs neither Docker nor Go — pick the file matching your OS and CPU architecture.

bash

# Download the archive for your platform from the latest release,
# unpack it, and put mcp-retrieval on your PATH.

mcp-retrieval          # stdio transport, no configuration needed

Prebuilt archives are attached to every release.

Tools

Three read-only tools

Each returns a structured JSON payload matching its output schema. The SDK mirrors the same JSON into the text content block for clients that do not read structuredContent.

web_search

Runs one or more queries in parallel and returns per-query deduplicated, reranked snippets with links.

queries []string required: Executed in parallel.
max_results int = 5: Snippets per query, capped at MAX_RESULTS (20).
timeout_ms int64 = 5000: Whole-call timeout; clamped to the min and max from config.
date string: Freshness filter: d (day), w (week), m (month), y (year).

web_search_images

Runs one or more image queries in parallel and returns per-query deduplicated image results.

queries []string required: Executed in parallel.
max_images int = 5: Images per query, capped at MAX_IMAGES (10).
timeout_ms int64 = 5000: Whole-call timeout; clamped to the min and max from config.
date string: Freshness filter: d / w / m / y.

web_scrape

Downloads one or more pages in parallel and returns the main article text as Markdown.

urls []string required: Downloaded in parallel.
robots_txt bool = false: Respect the page's robots.txt.
timeout_ms int64 = 5000: Whole-call timeout; clamped to the min and max from config.
remove_links bool = false: Strip Markdown links from the text.
max_chars int = 20000: Truncate page text to N characters, capped at MAX_DOCUMENT_CHARS.

Both queries and urls lists are capped at MAX_QUERIES (10) items per call. Queries must be 512 characters or fewer; URLs 2048 or fewer, and http or https only. Every call returns one entry per query or URL, each with its own status — success, failed or timeout — so a partial failure still returns the items that did work.

Rationale

Why run it yourself

A hosted search API bills per query and holds a key you have to manage. This is the other shape of the same capability: a binary you run.

No API keys
Web search goes through DuckDuckGo Lite, image search through Bing Images. There is nothing to sign up for and no key to rotate.
Free and local
One static binary or one container on your own machine rather than a hosted endpoint. No account, no per-query billing, no quota.
Fast
Written in Go and shipped as a single binary. Every call fans out across the whole query or URL list concurrently, with per-item timeouts.
Idiomatic and layered
Clean architecture with dependencies pointing inward toward the domain, each layer talking to the next through interfaces. Contributions gate on go build, go vet and go test all green.
Model-ready output
Pages come back as readability-extracted Markdown, not raw HTML. Partial failures still return whatever worked, each item carrying its own success, failed, or timeout status.

Connect

Point a client at it

Clients that install from the MCP Registry build the invocation themselves and prompt for the variables declared in server.json. Everything else takes one of these blocks.

json

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

The env block is optional — command alone is enough.

json

{
  "mcpServers": {
    "retrieval": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MAX_RESULTS",
        "-e", "DEFAULT_TIMEOUT_MS",
        "ghcr.io/role1776/mcp-retrieval:latest"
      ],
      "env": {
        "MAX_RESULTS": "20",
        "DEFAULT_TIMEOUT_MS": "5000"
      }
    }
  }
}

Docker needs each variable named on the command line with -e for it to reach the process. -i is required — without it the container gets no stdin and the client sees the server die immediately.

bash

MCP_TRANSPORT=http mcp-retrieval

# listens on SERVER_PORT at MCP_PATH
# default: http://localhost:8080/mcp

A long-running streamable HTTP server, useful for remote or shared deployments. It exposes the identical tool set.

Engine

How the requests go out

All network work is delegated to retrieval-go. What it does on the way out is the reason the free sources stay reachable.

Sources
Web search uses DuckDuckGo Lite. Image search uses Bing Images. Page fetching runs the raw HTML through a readability extractor and converts the main article to Markdown, tables included.
No search-engine API keys are required.
Browser impersonation
Each request is sent from one of about eleven real browser profiles, picked at random. Every profile pairs a genuine TLS/JA3 fingerprint, via uTLS, with a matching User-Agent and client-hint headers.
Chrome 133/131/120 on Windows, macOS and Linux; Edge 131; Firefox 120 on Windows and macOS; Safari 18.4 on macOS; and iOS 18.4 Safari. Traffic looks like an ordinary browser rather than a Go HTTP client, which is what keeps the free sources reachable.
Response handling
Responses are transparently decompressed: gzip, br, zstd and deflate.
Keep-alive is disabled, so a pooled connection cannot pin a single fingerprint or exit IP across requests.
Proxy rotationoptional
Set PROXY_SCHEME, PROXY_HOST, PROXY_PORT, PROXY_LOGIN and PROXY_PASSWORD, and the adapter installs a proxy factory that appends a unique session-<id> to the proxy login on every request. With a session-based residential provider that yields a fresh exit IP per request, spreading load and avoiding rate limits. Without a proxy, requests go out directly.
Search and scrape move small text responses, not video, so on a cheap pay-as-you-go residential plan the bandwidth cost of a thousand queries sits an order of magnitude below what a hosted search API charges per-query for the same thousand. The repository does not measure this, so no figure is quoted here — check it against your own provider's rate.

None of this needs configuration to work. The defaults are applied automatically; only the proxy credentials are optional extras.

Configuration

Environment variables

Everything is configured through environment variables, and each value is validated before startup: a non-numeric or non-positive value is a startup error. Variables already present in the environment win over the .env file, so an MCP client's env block always takes effect. Every field has a default, so the server runs with no configuration at all.

MCP server

The version advertised to clients is stamped in at build time from the git tag, not configurable.3

Environment variables in the MCP server group, with defaults.
Env	Default	Notes
MCP_TRANSPORT	stdio	stdio or http.
MCP_NAME	mcp-retrieval	Server name advertised to clients.
MCP_PATH	/mcp	HTTP route (http transport only).

HTTP server

http transport only.3

Environment variables in the HTTP server group, with defaults.
Env	Default
SERVER_PORT	8080
SERVER_READ_TIMEOUT	60s
SERVER_WRITE_TIMEOUT	60s

HTTP client and proxy

Environment variables in the HTTP client and proxy group, with defaults.
Env	Default	Notes
MAX_IDLE_CONNS_PER_HOST	100	HTTP connection pooling.
PROXY_HOST	—	Optional. If set, requests are routed through a rotating-session proxy.
PROXY_PORT	—	Required when PROXY_HOST is set.
PROXY_SCHEME	—	Required when PROXY_HOST is set.
PROXY_LOGIN	—	Required when PROXY_HOST is set.
PROXY_PASSWORD	—	Required when PROXY_HOST is set.

Limits

Each value must be greater than zero, but the DEFAULT/MIN/MAX triples are not cross-checked at startup — they are reconciled per request instead.10

Environment variables in the Limits group, with defaults.
Env	Default
MAX_QUERIES	10
DEFAULT_RESULTS	5
MAX_RESULTS	20
DEFAULT_TIMEOUT_MS	5000
MAX_TIMEOUT_MS	10000
MIN_TIMEOUT_MS	1000
DEFAULT_IMAGES	5
MAX_IMAGES	10
DEFAULT_DOCUMENT_CHARS	20000
MAX_DOCUMENT_CHARS	20000

Logging

Environment variables in the Logging group, with defaults.
Env	Default	Notes
LOG_MODE	local	local → text handler at debug level; prod → JSON handler at info level. Logs go to stderr.

The one command-line flag is -env, a path to a .env file. If it is omitted, or the file does not exist, the server starts on defaults and whatever is already in the environment. Limits are reconciled per request rather than cross-checked at startup: an omitted or non-positive value falls back to its DEFAULT_*, then is clamped into [MIN_*, MAX_*], and if MIN_* exceeds MAX_* the maximum wins. Misconfiguration degrades silently, so a typo such as MAX_RESULTS=2 quietly shrinks responses instead of failing the start. Full reference in the README.

← Back to the indexio.github.Role1776/mcp-retrieval

Web search for your LLM, without an API key.

Four ways to get the binary

Three read-only tools

web_search

web_search_images

web_scrape

Why run it yourself

No API keys

Free and local

Fast

Idiomatic and layered

Model-ready output

Point a client at it

How the requests go out

Sources

Browser impersonation

Response handling

Proxy rotationoptional

Environment variables

MCP server

HTTP server

HTTP client and proxy

Limits

Logging