websearch-mcp
Provides web and news search through the official Brave Search API when a key is configured, and also participates in the fallback engine chain used by the server's search tools.
Provides web search results through the ddgs aggregator, which queries DuckDuckGo and falls back across other engines when rate-limited.
Provides GitHub repository and issue search through the official GitHub REST API, with optional token support for higher rate limits.
Provides news search results via the zero-key Google News RSS feed, including article dates, sources, and region-specific editions.
Provides web search results as part of the ddgs fallback engine chain used by the server's search tool.
Allows the server to query a configured SearXNG instance with JSON output enabled as a first-choice web search backend before Brave or ddgs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@websearch-mcp search the web for the latest Python 3.14 release notes"
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.
websearch-mcp
Local-first, zero-key, zero-quota web search MCP server. Five lean tools that give any MCP client (ZCode, Claude Code, Codex, generic MCP) web search, news search, semantic (neural) search, GitHub search and a token-efficient page/PDF fetcher — with no API keys, no signups and no hosted service metering your account.
Why: built-in web search tools of AI coding plans are hosted and account-quota-metered. When the quota runs out, the agent goes blind for days. This server runs entirely on your machine: search goes through the ddgs aggregator library, which queries DuckDuckGo / Bing / Brave / Mojeek / Yahoo and falls back across engines when one rate-limits (403/429 are routine and handled). If you have a Brave Search API key, that official API is tried first instead.
Tools (5)
Tool | What it does |
| Web search: title / URL / snippet. Route: SearXNG (if configured) → Brave (if key) → |
| News search with dates and sources. Route: zero-key Google News RSS → Brave news → |
| Neural "find articles about X" search. Route: Exa → Tavily → |
| GitHub via the official REST API, no token needed ( |
| GET a page → reader-mode main content (links + tables kept, via |
Everything is cached in a local sqlite file next to the script (search 24 h, pages 7 d), so repeated queries cost zero tokens and zero engine hits — cache hits are marked [local cache, Nh old].
Related MCP server: ddgs-mcp
Install
Requires uv (or any Python ≥ 3.10 with pip) — Python 3.12 recommended.
# from this repo
uv venv ~/.venvs/websearch-mcp --python 3.12
uv pip install --python ~/.venvs/websearch-mcp git+https://github.com/xronocode/websearch-mcpThen register with your MCP client (user scope, adjust paths to your machine). Example for ZCode (~/.zcode/cli/config.json) — Claude Code / Codex / others use their equivalent config:
{
"mcp": {
"servers": {
"websearch": {
"type": "stdio",
"command": "/home/you/.venvs/websearch-mcp/bin/websearch-mcp",
"enabled": true
}
}
}
}Or run from a source checkout: command: <python>, args: ["/path/to/server.py"]. No templates are expanded — use absolute paths.
Environment variables (all optional)
Var | Effect |
| Use the official Brave Search API first in |
| Enable Exa neural search as the first engine of |
| Enable Tavily as the second engine of |
| Try a SearXNG instance with JSON format enabled before Brave/ |
| Raises GitHub API rate limits for |
|
|
Comparison (as of Oct 2026 — check upstreams, this space moves fast)
websearch-mcp | hosted built-ins | |||||
API keys / quota | none / none | none / none | none / none | none / none | none / none | account quota |
Footprint | 1 venv, ~200 MB deps | Python, 11 tools | MCP + CLI + daemon | Node ≥ 20, ~1.5 GB incl. browser engine + on-device models | light | zero local |
Engines | routed per tool: Brave / GNews RSS / Exa / Tavily (optional keys) → ddgs chain + region fallback | multi-engine, RRF-merged | bing/baidu/ddg/brave/startpage/sogou/HN (CN-leaning) | many | DDG only | vendor |
Fetch + extraction | trafilatura + raw fallback | trafilatura + more | article fetch | yes | fetch + parse | yes (some digest server-side) |
text-based | PDF/DOCX/XLSX/PPTX/EPUB | ✗ | yes | ✗ | varies | |
Local cache | sqlite, 24 h / 7 d | FTS5 | ✗ | yes | ✗ | ✗ |
Cyrillic auto-region | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ |
GitHub search | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ |
Browser dependency | none (JS pages → your browser tool) | optional Chromium for some engines | ✗ | ships its own | ✗ | n/a |
Per-session tool-schema cost | 5 lean tools, ~3.5 KB | 11 rich tools | few | many | few | n/a |
License | MIT | MIT | MIT | AGPL-3.0 | MIT | — |
When to pick something else: free-search-mcp if you want the research-combine-harvester (RRF merge, doc formats, one-shot research()) and don't mind the 11-tool context tax and an external dependency; wigolo if you want the full local web intelligence stack and have 1.5 GB + GPU to spare; open-webSearch if your targets are CN dev resources; hosted built-ins when your quota is alive and quality matters most.
Security & trust model
Audited (manual + local model review) before first publish and covered by a hermetic pytest suite in CI — the SSRF guard, redirect vetting, cache TTL, region routing and RSS parsing all have executable assertions. Posture:
fetchallows onlyhttp/httpsand refuses hosts that resolve to private / loopback / link-local addresses, re-resolving and re-checking every redirect hop before that hop is sent (SSRF guard). Opt in explicitly withWEBSEARCH_ALLOW_PRIVATE_HOSTS=1.Response bodies are capped at 20 MB; all outbound calls have timeouts; PDF parsing is capped at 40 pages.
No shell, no
eval, no subprocesses. No secrets in code;GITHUB_TOKENis read from the environment and only ever sent toapi.github.com.Prompt injection: text returned by
fetch/searchcomes from the open web and must be treated by the caller (LLM or human) as untrusted data, not instructions. This caveat applies to every web tool.Privacy: queries leave your machine directly to the search engines from your IP (inherent to any search). No third-party service sits in between, and nothing about your queries is sent anywhere else.
Limitations (honest)
Search quality is below a live Google-grade engine: some engines rate-limit per IP (the chain survives, individual engines come and go; the cache absorbs repeats). For rare queries a hosted engine still wins.
JS-rendered or bot-walled pages return little text — that's the browser-automation signal; this server deliberately does not bundle a browser.
Scanned PDFs (image-only) are not OCR'd.
No global per-call deadline yet: a
searchwhose whole chain fails can take up to ~60 s before it returns an error.
Tests
Hermetic: no network, no API keys — DNS, HTTP and the cache file are stubbed.
uv venv .venv --python 3.12
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytestCI runs the suite on Python 3.10, 3.12 and 3.13.
License
Available Tools
5 toolsfetchARead-onlyIdempotent
Free LOCAL URL fetch, no provider quota: GET the page and return readable text. HTML pages -> extracted main content with links and tables kept (much fewer tokens than raw dump); PDF -> extracted text (text-based PDFs only, scanned need OCR). Only public http/https URLs; redirects are vetted hop by hop; response capped at 20 MB, maxlen capped at 30000. Cached locally for 7 days. If a page yields almost no text (JS-rendered or blocked), returns a note to use browser automation for that URL.
Inputs: url (required), maxlen. Returns: result
searchARead-onlyIdempotent
Free LOCAL web search, no provider quota. DEFAULT choice for web search in this environment: try this tool first; use the built-in WebSearch only if this one errors. Returns numbered results (title, URL, snippet) and an [engine: ...] tag showing who answered. region optional ('ru-ru', 'us-en'); empty = auto (Cyrillic -> ru-ru first). max_results is capped at 20. Results cached locally for 24h. Docs of libraries need no special engine: search 'site:docs...' + fetch the page.
Inputs: query (required), region, max_results. Returns: result
search_githubARead-onlyIdempotent
Free LOCAL GitHub search via the official REST API, no key needed (set GITHUB_TOKEN env for higher limits). kind='repos': find repositories by topic/name/description (sorted by stars). kind='issues': bug reports and discussions. Useful to find tools, code examples, whether something is maintained. Cached 24h.
Inputs: query (required), kind, max_results. Returns: result
search_newsARead-onlyIdempotent
Free LOCAL news search, no provider quota. Use for fresh announcements, launches, tariff/partnership news. Route: Google News RSS (zero-key) -> Brave news -> ddgs. region optional ('de-de', 'us-en') selects the Google News edition and the ddgs region; empty = auto from the query script. Returns title, URL, source, date and an [engine: ...] tag. Results cached 24h.
Inputs: query (required), region, max_results. Returns: result
search_semanticARead-onlyIdempotent
Free LOCAL semantic/neural web search. Use for meaning-style research queries — 'articles about X', 'how companies solve Y', solution discovery — where keyword search misses. Route: Exa (neural) -> Tavily -> ddgs fallback; Exa/Tavily join only when their keys are installed (~/.config/websearch-mcp/exa.key / tavily.key). Returns title, URL, snippet, date and an [engine: ...] tag. Cached 24h.
Inputs: query (required), max_results. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
search_news, search_semantic and the generic search all perform web search with overlapping use cases; the descriptions give routing hints (e.g. 'articles about X' could reasonably go to search or search_semantic), so boundaries are not crisp. search_github and fetch are clearly distinct. An agent must read the routing prose carefully to pick correctly.
Four of five tools follow a search_<domain> pattern (search_news, search_semantic, search_github), and fetch is a clean verb. The bare 'search' breaks the pattern slightly where search_web would have been more consistent, but overall the convention is readable and predictable.
Five tools is well-scoped for a search/fetch server: general search, news, semantic, code search, and URL fetch each earn their place with no filler.
The surface covers the main research workflow (search → fetch → code/news lookup) with sensible fallbacks and caching. Minor gap: when a page is JS-rendered the fetch tool points users to 'browser automation' but no such tool exists, leaving a dead end, and there is no image or pagination support beyond max_results=20.
Maintenance
Related MCP Connectors
Free web search for AI agents. No API key required. Hosted MCP in active development.
Web search API and MCP server for developers building AI agents.
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.
Scrape, crawl and search the web for AI agents via MCP.
Related MCP Servers
- AlicenseAqualityBmaintenanceA 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.611181MIT
- AlicenseAqualityCmaintenanceEnables keyless multi-engine web, news, image, and video metasearch plus full-page markdown extraction for AI agents over MCP, with resilient fallback across DuckDuckGo, Bing, Brave, Google, and other backends.6MIT
- AlicenseAqualityCmaintenanceFree web search, web-page reading as Markdown, and llms.txt documentation retrieval for MCP clients. Runs locally with Node.js over stdio using @alkasima/alka-search-mcp. Searches DuckDuckGo, Mojeek, and Brave; default providers require no API key. Website and provider availability may vary.8331 npmMIT
- AlicenseAqualityCmaintenanceEnables any MCP client to run keyless multi-engine web searches with RRF fusion, fetch pages and documents as Markdown, and full-text search a local SQLite index. It keeps queries and cached content on the user's machine, degrading gracefully across engine tiers when providers are blocked or rate-limited.8MIT