# web-retrieval-mcp

> An open-source Model Context Protocol (MCP) server that gives AI agents two high-fidelity web tools — neural web search (Exa) and a tiered web fetch (Exa → optional local browser → Firecrawl) — as a drop-in replacement for built-in WebSearch/WebFetch. Provenance-preserving, SSRF-guarded, cross-platform (macOS/Linux/Windows), and free to run on the Exa and Firecrawl free tiers.

## What it provides

- Tool `web_search(query, num_results=8, mode="auto")`: neural/keyword/auto web search via Exa; returns one block per result (title, URL, highlights, text) plus a Sources list — never a merged summary.
- Tool `web_fetch(url, render="auto", max_chars=20000, max_age_hours=None)`: fetch one URL's readable content through a fallback chain (Exa contents → optional local camoufox browser when render="always" → Firecrawl), with a `[served by: …]` provenance header.
- A Claude Code PreToolUse hook (`deny-web-builtins.sh`) plus installer (`web-retrieval-mcp-install`) that disables built-in WebSearch/WebFetch so agents use these tools instead.

## Install and run

- Run without installing: `uvx web-retrieval-mcp`
- Install CLI: `pipx install web-retrieval-mcp` (or `pip install web-retrieval-mcp`)
- Optional extras: `pip install "web-retrieval-mcp[render]"` (local browser), `pip install "web-retrieval-mcp[keyring]"` (native secret store)
- Register with Claude Code: `claude mcp add web-retrieval -- web-retrieval-mcp`
- API keys (free): set env vars `EXA_API_KEY` (https://exa.ai) and `FIRECRAWL_API_KEY` (https://firecrawl.dev)

## Key facts

- License: MIT. Language: Python 3.10+. Transport: MCP over stdio.
- Free tiers: Exa 1,000 requests/month and Firecrawl 1,000 pages/month, no credit card; the local browser tier is free and unlimited.
- Cross-platform key resolution: env vars → key file → `keyring` library → OS secret CLI (macOS `security`, Linux `secret-tool`).
- Security: rejects non-public hosts (loopback, RFC-1918, link-local, multicast, NAT64) before any request.

## Links

- Repository: https://github.com/VelvetSP/web-retrieval-mcp
- README: https://github.com/VelvetSP/web-retrieval-mcp/blob/main/README.md
- Agent guide: https://github.com/VelvetSP/web-retrieval-mcp/blob/main/AGENTS.md
- Exa API: https://exa.ai · Firecrawl API: https://firecrawl.dev · MCP: https://modelcontextprotocol.io
