webfetch

webfetch

Web search for LLM agents that you run yourself - up to 8x fewer input tokens and 3x lower cost than hosted web_search, at the same accuracy.

Hosted web-search tools charge $10 per thousand searches and then bill you again for every token of retrieved content they push into your context window. webfetch replaces them with a local pipeline - multi-engine search, page fetching and extraction, semantic reranking, sentence-level compression - exposed as a web_search tool your model calls like any other. And unlike every hosted tool and search API we surveyed, repeated and paraphrased queries are served from a semantic cache for free.

(Install with pip install webfetch-llm; the import name is webfetch.)

Jump to: The headline · What you get · Getting started · Check your setup · Full benchmark results · Claude Code · Agent loop · Savings report · How it works · Caveats

Same accuracy. A third of the cost. An eighth of the tokens.

One agent loop, one model, one judge, 50 SimpleQA questions. The only thing that changes between rows is the search tool:

Swap Opus for gpt-5.6-sol and the same webfetch tool hits 96% - hosted parity - at $0.040/query and 2,156 tokens: an eighth of what the hosted tool pushes into your context. Full results cover every arm we ran.

These numbers are the WORST case for webfetch - measured on an empty cache. In real use the gap widens on its own: repeats and rewords serve from cache for free, and the token advantage is paid again on every later turn that keeps search results in context. It adds up to receipts like this one, from an ordinary Claude Code session:

Every claim in this README is generated by an eval harness that ships in this repo - the question sets, per-question records, judging protocol, and the negative results are all in evals/, and every table can be regenerated with one command. Don't take our word for the grading: evals/results/README.md maps every table row to the raw result file that produced it, down to per-question judge verdicts.

What you get

A search pipeline you own (4-engine RRF fusion, local extraction, sentence-level compression). Results come from reciprocal-rank fusion across DuckDuckGo, Brave, Serper, and Tavily - whichever of them you have keys for. DDG needs no key, so the tool works at literally zero cost out of the box; every key you add joins the fusion automatically. Pages are fetched and extracted locally (trafilatura, readability, newspaper4k, Playwright rendering for JS pages and 403 walls), chunked, ranked by a hybrid BM25 + bi-encoder cascade with a cross-encoder on top, then compressed to the sentences that answer the query - measured 50% fewer tokens at zero recall loss.

Caching nobody else has (exact + semantic matching, volatility-aware TTLs). Two layers in one sqlite file: page text by URL, ranked results by query. Identical queries hit an exact cache. Paraphrased queries hit a semantic cache - an embedding shortlist verified by an NLI cross-encoder, tuned eval-first for precision (zero wrong-target matches across every live run we have done). Cache lifetimes adapt to the query: prices and scores expire in 15 minutes, current-ish topics in 7 days, release notes and specs in 90 - classified by the calling model's hint or a local classifier. The model sees provenance on every cached result ([cache: semantic match to "...", 2h old, recent]) and can send force_fresh when it disagrees. No hosted tool or search API we surveyed offers any client-visible caching at all.

The model can maintain its own cache (save_finding, labeled UNVERIFIED, kill switch included). If a search comes up empty and the model answers from some other source (a hosted search fallback, say), it can call save_finding to store what it learned - marked model-contributed, served with an explicit UNVERIFIED warning and a force_fresh escape hatch, and aged out on the normal TTL rules. A kill switch (SAVE_FINDING_ENABLED = False) exists for deployments that never want unverified content cached.

Levers where models actually need them (full_results, fetch_url, freshness, force_fresh). full_results returns uncompressed excerpts for list and ranking queries (compression trims parallel list items - we measured it). fetch_url pulls one cited page in full, instantly if the pipeline has ever fetched it. freshness hints control cache lifetime; force_fresh bypasses it.

Receipts (session and lifetime, exact counters). Usage counters persist in the cache file; webfetch-savings (or the savings_report tool) shows what you did not pay hosted-search pricing for, split by this session and lifetime. Sample below.

Getting started

The one-liner (uv installs the package on first launch, @latest picks up new releases automatically):

claude mcp add webfetch -- uvx --from webfetch-llm@latest webfetch-mcp

Or manage the install yourself, two commands:

pip install "webfetch-llm[all]"

claude mcp add webfetch -- webfetch-mcp

The slim install (webfetch-llm without extras) starts in seconds and runs degraded: BM25 ranking, exact-only cache, lexical compression. [all] pulls the semantic stack (torch - a few minutes once) plus Playwright, PDF, and table extraction; it is the configuration every benchmark number in this README was measured on. Needs pip >= 24 in fresh venvs (python -m pip install -U pip - older pips crash on a duplicated extra in our dependency tree). If you install into a venv, register the absolute path to webfetch-mcp or keep the venv active.

Keys are optional (DDG works with none) but improve recall - all the engines have free tiers:

cp .env.example .env    # fill in what you have

The console scripts and the MCP server pick up a .env from the directory they run in; exported env vars and --env flags on claude mcp add always take precedence. import webfetch as a library never reads .env - your process env is yours.

Check your setup

webfetch-status (or asking the model to call the status tool) answers "is my key being picked up, and what am I actually running?":

webfetch 0.1.3

search engines: ddg ready (no key needed) brave ready (BRAVE_API_KEY is set) serper off (SERPER_API_KEY not set) tavily ready (TAVILY_API_KEY is set)

active provider: multi(ddg+brave+tavily) (RRF fusion)

optional features: semantic ranking/cache/compression: on JS-page rendering (playwright): on PDF extraction (pdfplumber): OFF (pip install 'webfetch-llm[pdf]') HTML tables (pandas+tabulate): on result compression: on (crossencoder)

cache: /Users/you/.webfetch/cache.db 5.4 MB, 70 lifetime searches (webfetch-savings for the receipt)

Key names only - values are never printed. Configuration is environment variables, read at server start:

With zero keys the default resolves to plain DDG; the status output says so honestly rather than calling it fusion. Library users can skip env entirely: Pipeline(search=get_search_adapter("fallback"), cache=...).

Full benchmark results

Every arm, same 50 SimpleQA questions, same judge, one same-day run (2026-07-14). Agent-loop arms share an identical loop; only the search tool differs. Costs include model tokens plus each provider's published per-search fees; ours include estimated engine fees.

\* Haiku's failures were mostly re-searching past the turn cap, and its last few questions ran on a degraded engine set after we exhausted a free tier mid-benchmark. Treat it as a floor.

Notice the token column: webfetch results cost half the input tokens of the snippet APIs and a fifth to an eighth of the hosted tools - which is why our cost stays lowest even where per-search fees are similar.

On a second dataset of 27 questions about events from the two weeks before the run (hand-written, never published, so no vendor could have tuned on them), webfetch scored 100% with fusion and 100% with DDG alone; the hosted tools also scored 100%. Fresh events are not the hard part - the date-injection trap is.

Reproduce: python evals/run_e2e_eval.py --arms ours-multi,hosted - the harness, datasets, and per-question records are in evals/. The table above comes from e2e_eval_20260714_005531.json (plus the Haiku run and the fresh-events set - the full claim-to-file map is in evals/results/README.md). The questions are a seeded sample (seed 42) of OpenAI's public SimpleQA set, so build_datasets.py regenerates the identical 50 on your machine. One honest caveat: the live web moves between runs, and at n=50 the 96-vs-92 accuracy gap is 48-vs-46 correct - parity within noise. The token and cost columns are the mechanically stable result.

Using it in Claude Code / Claude Desktop

Fastest route in Claude Code - install it as a plugin, two slash commands (runs the same uv one-liner under the hood):

/plugin marketplace add firish/webfetch

/plugin install webfetch@webfetch

Or register the MCP server yourself. Either way, a new session shows webfetch under /mcp with five tools: web_search, fetch_url, save_finding, status, and savings_report. Ask anything recent and watch the tool calls; ask the same thing reworded and the result comes back with a [cache: semantic match ...] header instead of a fresh search. First call in a session is slow (encoder warm-up plus real page fetches, 10-40s); cached calls are instant.

Toggle the server off per-session in /mcp; remove it with /plugin uninstall webfetch or claude mcp remove webfetch, matching how you installed it. Your cache and its receipt history live in ~/.webfetch/ and survive reinstalls. Run one server per machine - the semantic cache assumes a single process owns its file.

Update notice: the server makes one request to pypi.org per process to check for a newer release, surfaced as one line in savings_report output. UPDATE_CHECK_ENABLED = False in webfetch/config.py disables it; nothing else is ever sent anywhere.

Use it in your own agent loop

import time

import anthropic from webfetch import WEB_SEARCH_TOOL, handle_web_search

client = anthropic.An