What can you do with this server?

Summary: mcp-retrieval is a read-only MCP server for keyless web retrieval through three tools. * Web search (web_search): run up to 10 English queries in parallel and get snippets with links, per-query counts, freshness filters (d/w/m/y), and query operators like site:, filetype:, quotes, -, and intitle:. * Image search (web_search_images): run up to 10 English image queries in parallel and get image URLs, page URLs, descriptions, freshness filters, and a per-query image limit. * Page scraping (web_scrape): fetch up to 10 URLs in parallel and return the main article text as Markdown, optionally respecting robots.txt and stripping links, with per-page truncation up to 20,000 characters and truncation reporting. * Call behavior: returns structured per-item results with success/failed/timeout statuses and metadata, so partial failures still return usable results. * Transport: can run over stdio by default or as a streamable HTTP server.

Which integrations are available for this server?

Provides web search capabilities through DuckDuckGo, allowing agents to search the web and retrieve snippets with links.

How do I use mcp-retrieval?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-retrieval search the web for recent advances in quantum computing" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

mcp-retrieval

by Role1776

Overview Schema Source Related Servers Discussions Admin

Hybrid

What it is

mcp-retrieval is a Model Context Protocol server written in Go. It exposes web retrieval capabilities to any MCP-compatible client (Claude Desktop, IDE agents, custom LLM apps) as three read-only tools. Under the hood it uses the retrieval-go library to search the web and fetch pages, returning results as clean Markdown ready to hand to a model.

The library needs no API keys: web search goes through DuckDuckGo Lite, image search through Bing Images, and page fetching runs the HTML through a readability extractor before converting it to Markdown. To stay reliable against bot protection it impersonates real browsers at the TLS level and can rotate both browser fingerprints and proxies — see Retrieval engine.

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

Related MCP server: mcp-web-calc

Tools

Tool	Description
`web_search`	Runs one or more queries in parallel and returns per-query deduplicated, reranked snippets with links.
`web_search_images`	Runs one or more image queries in parallel and returns per-query deduplicated image results.
`web_scrape`	Downloads one or more pages in parallel and returns the main article text as Markdown.

All three are annotated as read-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 read structuredContent.

`web_search`

Parameter	Type	Default	Notes
`queries`	`[]string`	—	Required. Executed in parallel.
`max_results`	`int`	`5`	Snippets per query, capped at `max_results` config (`20`).
`timeout_ms`	`int64`	`5000`	Whole-call timeout; clamped to `[min, max]` from config.
`date`	`string`	—	Freshness filter: `d` (day), `w` (week), `m` (month), `y` (year).

`web_search_images`

Parameter	Type	Default	Notes
`queries`	`[]string`	—	Required. Executed in parallel.
`max_images`	`int`	`5`	Images per query, capped at `max_images` config (`10`).
`timeout_ms`	`int64`	`5000`	Whole-call timeout; clamped to `[min, max]` from config.
`date`	`string`	—	Freshness filter: `d` / `w` / `m` / `y`.

`web_scrape`

Parameter	Type	Default	Notes
`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 `[min, 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` config (`20000`).

Both queries/urls lists are capped at max_queries (10) items per call. Queries must be ≤ 512 characters; URLs ≤ 2048 characters and http/https only.

Results and counts

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

count is the number of items actually returned, and it can be lower than the requested max_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 smaller count is a normal outcome, not an error.

Deduplication is per 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.

Errors

Request-level failures are returned as a tool result with isError: true and 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 as status: "failed" / "timeout".

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

Message	Meaning
`invalid request`	The arguments did not pass validation.
`too many queries` / `too many urls`	The list exceeds `MAX_QUERIES`. Lists this long are normally rejected earlier by input-schema validation (the schema carries `maxItems`), so the client sees `validating "arguments": maxItems: ...` instead; this message is a fallback.
`query must not be empty`	An empty query, or an empty `queries` list.
`query is too long`	A query exceeds 512 characters.
`invalid url`	A URL is malformed, over 2048 characters, or not `http`/`https`.
`robots.txt denied`	`robots_txt: true` and the page disallows fetching.
`every url failed to be scraped; the pages may be unreachable or hold no extractable text`	Every URL failed with an error other than a timeout. Individual causes are logged to `stderr`, not returned.
`every query failed; the search upstream may be unreachable`	Every query failed with an error other than a timeout, including the upstream rejecting the requests (any non-200 answer, such as DuckDuckGo's HTTP 202 bot challenge under a burst of requests). The per-query cause is logged to `stderr`.
`request canceled`	The client canceled the call before it finished; nothing about the upstream is implied.
`internal server error`	Anything unclassified.

A timeout is never a call-level error: an item that runs out of time gets status: "timeout", and a call where every item timed out still returns all of them with that status. The all-failed messages only fire when no item succeeded or timed out.

Known limitations

web_scrape handles HTML only. Pages are run through a readability extractor, which needs article markup, so text/plain responses yield nothing and come back as status: "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_images relevance 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 with status: "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.
Bursts of parallel searches can trip DuckDuckGo's bot challenge. The challenge answers with HTTP 202, which counts as a failed query, so queries keep failing until the request rate drops. A rotating proxy (see HTTP client and proxy) spreads the load across exit IPs.

Quick start

Install

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

Container (no Go toolchain needed):

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

Prebuilt binary — grab the archive for your platform from the latest release, unpack it, and put mcp-retrieval on your PATH.

MCP Bundle — for clients that install .mcpb files, download mcp-retrieval_<version>_<os>_<arch>.mcpb from the latest release and open it with your client. The bundle carries the compiled binary, so it needs neither Docker nor Go. Pick the file matching your OS and CPU architecture: a bundle holds one native binary.

From source:

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 in app/):

make build          # -> bin/mcp-retrieval

Run

# defaults: stdio transport, no configuration needed
./bin/mcp-retrieval

# with an explicit env file
./bin/mcp-retrieval -env /absolute/path/to/.env

The one flag is optional:

Flag	Meaning
`-env`	Path to a `.env` file. If omitted — or if the file does not exist — the server starts on defaults and whatever is already in the environment. There is no implicit lookup: under stdio the working directory is chosen by the MCP client, so a relative default would be unpredictable.

Connecting an MCP client (stdio)

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

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

The env block is optional — "command" alone is enough.

Connecting an MCP client (container)

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

{
  "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"
      }
    }
  }
}

-i is required — without it the container gets no stdin and the client sees the server die immediately. Clients that install from the MCP Registry build this invocation themselves and prompt for the variables declared in server.json.

Running over HTTP

Set MCP_TRANSPORT=http and the server listens on SERVER_PORT at MCP_PATH (default http://localhost:8080/mcp).

Configuration

Everything is configured through environment variables, and each value is validated before startup: a non-numeric or non-positive value is a startup error (the *_IN_FLIGHT caps also accept 0). Relationships between limits are not checked at startup — see Limits. Variables already present in the environment win over a .env file, so an MCP client's env block always takes effect. Every field has a sensible default, so the server runs with no configuration at all (stdio transport).

See .env.example for the full list at its default values, ready to copy to .env.

MCP server

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

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

HTTP server (http transport only)

Env	Default
`SERVER_PORT`	`8080`
`SERVER_READ_TIMEOUT`	`60s`
`SERVER_WRITE_TIMEOUT`	`60s`

HTTP client and proxy

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.

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.

Limits

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`
`MAX_SEARCH_IN_FLIGHT`	`2`
`MAX_IMAGES_IN_FLIGHT`	`2`

MAX_SEARCH_IN_FLIGHT and MAX_IMAGES_IN_FLIGHT cap concurrent upstream web and image search requests per server process; 0 disables the cap.

Each value is checked on its own — it must be greater than zero, except the *_IN_FLIGHT caps, where 0 disables the cap — but the DEFAULT_*, MIN_* and MAX_* triples are not cross-checked against each other at startup. An inconsistent set does not stop the server; it is reconciled per request instead:

a value the caller omits, or passes as zero or negative, falls back to the matching DEFAULT_*;
the result is then clamped into [MIN_*, MAX_*], so a DEFAULT_* larger than its MAX_* simply yields MAX_*;
if MIN_* exceeds MAX_*, the maximum wins.

The effective limit is therefore always within the configured maximum, and misconfiguration degrades to a working server rather than a failed start. The trade-off is that it degrades silently: a typo such as MAX_RESULTS=2 instead of 20 produces no warning, only quietly smaller responses. Worth double-checking these values when results look truncated.

Logging

Env	Default	Notes
`LOG_MODE`	`local`	`local` → text handler at debug level; `prod` → JSON handler at info level. Logs go to `stderr`.

Architecture

The project follows a clean, layered structure. Dependencies point inward toward the domain, and each layer talks to the next through interfaces.

app/                       the Go module: sources plus its build files
                           (Dockerfile, .dockerignore, .goreleaser.yaml)

cmd/mcp-retrieval/main.go  entry point: parse flags, load config, run app

internal/
  app/                     wiring + lifecycle (build server, run, graceful shutdown)
  config/                  config loading (.env → env vars → validate)
  domain/                  core types (Query, Link, Document, Snippet, Image) and errors
  dto/web/                 request/response shapes for the MCP tools
  transport/mcp/           MCP layer
    router/                registers every tool group on the MCP server
    web/                   tool handlers
    utils/                 schema helpers and error → tool-result mapping
  usecase/web/             business logic: validation, parallelism, timeouts, dedupe/limit/rerank
  adapter/web/             retrieval-go client wiring (search, images, scrape, proxy)
  pkg/                     reusable building blocks (mcpserver, server, logger, validator)

Request flow for a tool call:

MCP client → transport/mcp/web (handler) → usecase/web → adapter/web → retrieval-go → the web
                     ↑ maps errors               ↑ validates, fans out, limits results

Search and scrape both fan out across the input list concurrently and aggregate per-item results, each with its own status (success, failed, timeout). A call only fails outright when every item in it fails with an error other than a timeout.

Retrieval engine

All network work is delegated to retrieval-go, configured in app/internal/adapter/web. Worth knowing:

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. The adapter enables WithBrowserRotation(), so each request is sent from one of ~11 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 (Windows/macOS/Linux), Edge 131, Firefox 120 (Windows/macOS), Safari 18.4 (macOS), and iOS 18.4 Safari. This makes the traffic look like ordinary browsers rather than a Go HTTP client, which is what keeps the free sources reachable.
Proxy rotation. When PROXY_HOST is configured, the adapter installs a proxy factory that appends a unique session-<id> to the proxy username on every request. With a session-based residential/rotating proxy provider, that yields a fresh exit IP per request, spreading load and avoiding rate limits. Without a proxy, requests go out directly.
Response handling. Responses are transparently decompressed (gzip, br, zstd, deflate), and keep-alive is disabled (WithDisableKeepAlive()) so pooled connections don't pin a single fingerprint/IP across requests.

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

Development

Everything Go lives in app/, so either use the makefile from the repository root or pass -C app to 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

See CONTRIBUTING.md for pull-request guidelines.

License

Released under the MIT License.

Available Tools

3 tools

web_scrapeWeb scrapeA

Read-onlyIdempotent

Downloads pages by their links and returns the main text as markdown. Use this to read a page in full after 'web_search' found it; snippets alone are often not enough. Links are fetched in parallel, up to 10 per call, so batch all links into one call.

Size: 'max_chars' is a per-page character limit (not tokens). A page cut short ends with '[truncated]' and has 'truncated' set; the rest cannot be fetched afterwards.

Results are reported per URL with a 'status' field (success, failed or timeout). A failed URL does not fail the others; the call errors only if every URL fails. Target sites may block or rate-limit the request, which shows up as a failed URL.

Name	Required	Description
`urls`	Yes	1-10 absolute http(s) page URLs, fetched in parallel; one malformed URL rejects the whole call
`max_chars`	No	character limit applied to each page separately, not to the whole response; default and maximum 20000, so it can only lower the limit; a cut page ends with '[truncated]'
`robots_txt`	No	if true, pages disallowed by the site robots.txt are not fetched; default false
`timeout_ms`	No	timeout for the whole call in milliseconds, shared by all URLs; default 5000, clamped to 1000-10000; unfinished pages get status 'timeout'
`remove_links`	No	if true, markdown links are replaced by their text; default false

Output Schema

Name	Required	Description
`results`	Yes
`metadata`	Yes

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description still adds real substance: per-URL status values, partial-failure semantics ('a failed URL does not fail the others'), all-fail error condition, external blocking/rate-limiting, and the irreversibility of truncation. Minor gap: it doesn't mention the robots_txt opt-in or the call-wide timeout being shared across URLs, both of which affect real call behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the batching rule, then cleanly separated into size and result-reporting sections. Every sentence carries a constraint or a consequence an agent would otherwise get wrong; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the things that actually break an agent's plan: batching limit, per-page truncation, partial failure isolation, and timeouts. An output schema exists, yet the description still summarizes the per-URL status contract, which is a useful addition rather than redundancy.

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, but the description adds interpretive value beyond the schema: 'max_chars' is a per-page limit, not tokens, and a cut page cannot be recovered afterwards. The remaining parameters (robots_txt, timeout_ms, remove_links) are left entirely to the schema, which is acceptable given full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Downloads pages by their links and returns the main text as markdown') and explicitly positions itself against the sibling 'web_search' by naming the gap in snippets. An agent can distinguish it from web_search and web_search_images without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit sequencing rule ('use this to read a page in full after web_search found it; snippets alone are often not enough') and an operational rule ('batch all links into one call'). The alternative tool is named together with the condition that selects it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

web_searchWeb searchA

Read-onlyIdempotent

Searches the web for one or more queries and returns snippets with links. Queries run in parallel. IMPORTANT: Always write search queries in English for best results and relevance. Use this to find sources; then call 'web_scrape' to read a full page, or 'web_search_images' when you need pictures (both can be called in the same turn).

Freshness: set the 'date' field to restrict results by recency - 'd' (past day), 'w' (past week), 'm' (past month), 'y' (past year). Use it to prefer the most recent pages when the user asks about news or anything time-sensitive; leave it empty for all time.

Query operators (put them inside the query string itself): 'site:example.com term' limits the search to one site; 'filetype:pdf term' restricts to a file type; double quotes "exact phrase" force an exact match; a leading '-' excludes a word (term -foo); 'intitle:term' requires the word in the page title. Operators can be combined, e.g. 'site:arxiv.org filetype:pdf transformers'.

Results are reported per query with a 'status' field (success, failed or timeout). A failed query does not fail the others; the call errors only if every query fails. The upstream search engines may rate-limit or block requests, which shows up as a failed or timed-out query - retry later or rephrase.

Name	Required	Description
`date`	No	freshness filter: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time; use only these values
`queries`	Yes	1-10 search queries in English, run in parallel; each must be non-empty and at most 512 characters, otherwise the whole call is rejected
`timeout_ms`	No	timeout for the whole call in milliseconds, shared by all queries; default 5000, clamped to 1000-10000; unfinished queries get status 'timeout'
`max_results`	No	maximum snippets per query, not in total; default 5, values above 20 are clamped to 20

Output Schema

Name	Required	Description
`results`	Yes
`metadata`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnly/openWorld/idempotent annotations: it explains per-query status reporting (success/failed/timeout), that a failed query does not fail the others and the call errors only if all queries fail, and that upstream rate-limiting surfaces as failed/timed-out queries requiring retry or rephrasing. That is exactly the operational context annotations cannot carry.

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?

Front-loaded with purpose before the operational detail, and section labels (Freshness, Query operators) make it scannable. Minor redundancy: the date filter values are spelled out in both the description and the schema's date property description, costing a sentence that adds no new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything an agent needs for a multi-query search tool: batching behavior, partial-failure semantics, timeout/rate-limit handling, query formatting, and result shape at a high level. An output schema exists, so return values need not be enumerated here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100%, the description adds substantial meaning: it mandates English queries, enumerates the supported query operators (site:, filetype:, quoted phrases, leading '-', intitle:) with a combined example, and explains freshness semantics. This is syntax guidance the schema does not express.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('searches the web') plus scope ('one or more queries', parallel execution, snippets with links). It explicitly distinguishes itself from both siblings by naming web_scrape for full-page reads and web_search_images for pictures.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use routing ('Use this to find sources; then call web_scrape...') and notes both can be called in the same turn. It also supplies conditional guidance for the date filter ('use it when the user asks about news or anything time-sensitive; leave it empty for all time').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

web_search_imagesWeb image searchA

Read-onlyIdempotent

Searches for images by one or more queries, executed in parallel. IMPORTANT: Queries must be in English ONLY. Use this only when you need pictures; use 'web_search' for text answers and links, and 'web_scrape' to read a page.

Freshness: set the 'date' field to restrict results by recency - 'd' (past day), 'w' (past week), 'm' (past month), 'y' (past year); leave it empty for all time.

Query operators can be embedded in the query string: 'site:example.com term' limits to one site, double quotes "exact phrase" force an exact match, and a leading '-' excludes a word.

Results are reported per query with a 'status' field (success, no relevant, failed or timeout). A failed query does not fail the others; the call errors only if every query fails. The upstream image search may rate-limit or block requests, which shows up as a failed or timed-out query.

Name	Required	Description
`date`	No	freshness filter: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time; other values are ignored
`queries`	Yes	1-10 image search queries in English, run in parallel; each must be non-empty and at most 512 characters, otherwise the whole call is rejected
`max_images`	No	maximum images per query, not in total; default 5, values above 10 are clamped to 10
`timeout_ms`	No	timeout for the whole call in milliseconds, shared by all queries; default 5000, clamped to 1000-10000; unfinished queries get status 'timeout'

Output Schema

Name	Required	Description
`results`	Yes
`metadata`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, yet the description still adds real value: per-query status semantics, partial-failure behavior ("a failed query does not fail the others"), and the upstream rate-limit/block risk. It does not explain result ordering or what fields come back, but the output schema covers that.

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?

Front-loaded with the core behavior and routing decision, then broken into scannable paragraphs for freshness, operators, and failure semantics. Slightly dense, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param parallel search tool with annotations and an output schema, this covers everything an agent needs: language constraint, batching, freshness, operator syntax, and failure modes. Nothing material is missing.

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 baseline is 3, and the description goes beyond it by documenting query operators (site:, "exact phrase", leading '-') that are absent from the schema entirely. The freshness codes and clamping are repeated from the schema rather than adding to it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Searches for images by one or more queries") plus the parallel-execution trait. It explicitly names both siblings and what each is for, so an agent can pick the right tool without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use condition ("use this only when you need pictures") and names the two alternatives with their respective purposes. The English-only constraint is flagged as IMPORTANT and front-loaded.

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.

3 tool updatesv0.1.10Oct 24, 2026

Changedweb_scrape6 fields changed

changedInput schema / properties / max_chars / description

Previous value: -"truncate each page separately to N characters, default and maximum 20000; only lowers the limit, higher values are ignored"New value: +"character limit applied to each page separately, not to the whole response; default and maximum 20000, so it can only lower the limit; a cut page ends with '[truncated]'"

changedInput schema / properties / remove_links / description

Previous value: -"strip markdown links from the text"New value: +"if true, markdown links are replaced by their text; default false"

changedInput schema / properties / robots_txt / description

Previous value: -"respect the page robots.txt"New value: +"if true, pages disallowed by the site robots.txt are not fetched; default false"

changedInput schema / properties / timeout_ms / description

Previous value: -"timeout for the whole call in milliseconds"New value: +"timeout for the whole call in milliseconds, shared by all URLs; default 5000, clamped to 1000-10000; unfinished pages get status 'timeout'"

changedInput schema / properties / urls / description

Previous value: -"links to pages, downloaded in parallel"New value: +"1-10 absolute http(s) page URLs, fetched in parallel; one malformed URL rejects the whole call"

addedInput schema / properties / urls / maxItems
```
Added value: +10
```

Changedweb_search5 fields changed

changedInput schema / properties / date / description

Previous value: -"filter results by freshness: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time"New value: +"freshness filter: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time; use only these values"

changedInput schema / properties / max_results / description

Previous value: -"maximum number of snippets per query"New value: +"maximum snippets per query, not in total; default 5, values above 20 are clamped to 20"

changedInput schema / properties / queries / description

Previous value: -"search queries in English, executed in parallel"New value: +"1-10 search queries in English, run in parallel; each must be non-empty and at most 512 characters, otherwise the whole call is rejected"

addedInput schema / properties / queries / maxItems
```
Added value: +10
```

changedInput schema / properties / timeout_ms / description

Previous value: -"timeout for the whole call in milliseconds"New value: +"timeout for the whole call in milliseconds, shared by all queries; default 5000, clamped to 1000-10000; unfinished queries get status 'timeout'"

Changedweb_search_images5 fields changed

changedInput schema / properties / date / description

Previous value: -"filter results by freshness: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time"New value: +"freshness filter: 'd' past day, 'w' past week, 'm' past month, 'y' past year; empty means all time; other values are ignored"

changedInput schema / properties / max_images / description

Previous value: -"maximum number of images per query"New value: +"maximum images per query, not in total; default 5, values above 10 are clamped to 10"

changedInput schema / properties / queries / description

Previous value: -"queries in English for image search"New value: +"1-10 image search queries in English, run in parallel; each must be non-empty and at most 512 characters, otherwise the whole call is rejected"

addedInput schema / properties / queries / maxItems
```
Added value: +10
```

changedInput schema / properties / timeout_ms / description

Previous value: -"timeout for the whole call in milliseconds"New value: +"timeout for the whole call in milliseconds, shared by all queries; default 5000, clamped to 1000-10000; unfinished queries get status 'timeout'"

3 tool updatesv1.0.0Aug 22, 2026
- First observedweb_scrape
- First observedweb_search
- First observedweb_search_images

Deploy Server

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

TDQS

A4.7/5.0

Scored 2026-10-24 17:35 across 3 tools

Disambiguation5/5

Each tool targets a distinct modality+action: text search, image search, and full-page fetching. The descriptions explicitly cross-reference each other ('use web_search for text, web_scrape to read a page'), leaving no realistic chance of misselection.

Naming Consistency5/5

All three names follow the same snake_case verb_noun pattern sharing the 'web_' prefix (web_search, web_search_images, web_scrape). The shared prefix makes the family immediately recognizable while the distinguishing suffix stays descriptive.

Tool Count5/5

Three tightly scoped tools for a retrieval-only server; none is redundant and no filler exists. Search-text, search-images, and scrape cover the full surface without bloat.

Completeness4/5

The retrieve-then-read workflow is fully supported, with batching, truncation signaling, and per-URL status handling. Minor gaps remain (no structured/raw fetch beyond markdown extraction, no crawl or sitemap traversal), but agents can work around these via repeated scrape calls.

Maintenance

ActivityMaintained

ResponsivenessSlow

Resources

Related MCP Connectors

SSearch B
cc.ssearch
Free web search for AI agents. No API key required. Hosted MCP in active development.
Search Browser Automation
82
https://api.ssearch.cc/mcp
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
https://llmse.ai/mcp
Keenable Web Search A
ai.keenable.api
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Research & Data Search Web Scraping
23
https://api.keenable.ai/mcp?keenable_title=glama
Novada MCPOAuth
io.github.NovadaLabs
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Browser Automation Web Scraping Search
13
https://mcp.novada.com/mcp

Related MCP Servers

ISIS MCP
RAG Systems Web Scraping Search
alucardeht
A
license
B
quality
D
maintenance
A local web scraping MCP server with RAG capabilities that provides intelligent web search, content extraction, and screenshot tools without requiring API keys.
Updated 8 months ago (2026-02-25 04:07 UTC)
4
6 npm
MIT
mcp-web-calc
Search Browser Automation Text Summarization
tickernelz
A
license
A
quality
D
maintenance
An MCP server that enables web searching, URL content extraction, and summarization without requiring API keys. It also provides advanced mathematical evaluation and multi-language Wikipedia summary retrieval tools.
Updated 6 months ago (2026-05-03 08:45 UTC)
5
400 npm
7
MIT
free-search-mcp
Browser Automation Search Web Scraping
sweetcornna
A
license
A
quality
A
maintenance
A local-first, no-API-key MCP server that enables LLMs to search the web, fetch pages, and read documents using multiple engines and smart fallbacks.
Updated 2 days ago (2026-10-29 08:11 UTC)
11
167
MIT
web-basics-mcp
Browser Automation Search
yoloyash
A
license
A
quality
A
maintenance
A self-hosted MCP server providing web search and URL fetching tools, running locally without external API keys or accounts.
Updated 2 months ago (2026-08-26 07:41 UTC)
2
380 npm
MIT