Model Context Protocol server

Web search for your LLM.
No API keys.

An MCP server in Go that exposes web_search, web_search_images and web_scrape to any MCP client. It runs locally, it is free, and it is fast.

Get started View on GitHub

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 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.

MIT licence
Go 1.25+
stdio & HTTP
In the MCP Registry

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.

Parameters for web_search
Parameter	Type	Default
queries	[]string	—
max_results	int	5
timeout_ms	int64	5000
date	string	—

queries: — Required. Executed in parallel.
max_results: — Snippets per query, capped at MAX_RESULTS (20).
timeout_ms: — Whole-call timeout; clamped to [min, max] from config.
date: — 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.

Parameters for web_search_images
Parameter	Type	Default
queries	[]string	—
max_images	int	5
timeout_ms	int64	5000
date	string	—

queries: — Required. Executed in parallel.
max_images: — Images per query, capped at MAX_IMAGES (10).
timeout_ms: — Whole-call timeout; clamped to [min, max] from config.
date: — Freshness filter: d / w / m / y.

web_scrape

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

Parameters for web_scrape
Parameter	Type	Default
urls	[]string	—
robots_txt	bool	false
timeout_ms	int64	5000
remove_links	bool	false
max_chars	int	20000

urls: — Required. Downloaded in parallel.
robots_txt: — Respect the page's robots.txt.
timeout_ms: — Whole-call timeout; clamped to [min, max] from config.
remove_links: — Strip Markdown links from the text.
max_chars: — Truncate page text to N characters, capped at MAX_DOCUMENT_CHARS (20000).

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.

Why

Why mcp-retrieval

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.

Setup

Connect a client

Point your MCP client at the binary or the container. Clients that install from the MCP Registry build the invocation themselves and prompt for the variables declared in server.json.

json

{
  "mcpServers": {
    "retrieval": {
      "command": "/absolute/path/to/app",
      "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

Retrieval engine

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.

On the cost of that traffic

Search and scrape move small text responses, not video. On a cheap pay-as-you-go residential plan the bandwidth cost of a thousand queries is therefore 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, validated before startup. 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

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_VERSION	0.1.1	Server version advertised to clients. Identifies the build.
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

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. Full reference in the README.

Web search for your LLM.No API keys.

Three read-only tools

web_search

web_search_images

web_scrape

Why mcp-retrieval

No API keys

Free and local

Fast

Idiomatic and layered

Model-ready output

Connect a client

Retrieval engine

Sources

Browser impersonation

Response handling

Proxy rotationoptional

Environment variables

MCP server

HTTP server

HTTP client and proxy

Limits

Logging

Web search for your LLM.
No API keys.