freesearch-mcp Server

freesearch-mcp

Free web search for AI agents — no API key required.

An MCP server that routes search queries through public SearXNG instances. Instead of paying per query to SerpAPI, Exa, or Brave Search, this server fans out to multiple public SearXNG instances simultaneously, merges the results, and returns the best ones.

Claude Code / any MCP client
         ↓
  freesearch-mcp
         ↓
  Best SearXNG instances (auto-discovered)
         ↓
  Merged, deduplicated search results

---

Tools

Tool	Description
web_search	General web search with multi-instance fan-out and Reciprocal Rank Fusion ranking
news_search	Recent news articles with publication dates
image_search	Image search returning image URL, thumbnail URL, title, and source page
extract_page	Fetch any URL and return its main content as clean markdown
best_instance	Returns the top-ranked SearXNG instance with its score, latency, uptime, engine count, and JSON support status

---

Quick start

Claude Code

claude mcp add freesearch -s user -- npx -y freesearch-mcp

Or add manually to ~/.claude/claude.json:

{ "mcpServers": { "freesearch": { "command": "npx", "args": ["-y", "freesearch-mcp"] } } }

Then ask Claude: "search for 'typescript generics' and summarize the top results"

Other MCP clients

Test interactively

npx -y @modelcontextprotocol/inspector npx -y freesearch-mcp

Opens a browser UI at http://localhost:6274 where you can call each tool manually.

---

How it works

Multi-instance fan-out

Every search fans out to all available SearXNG instances simultaneously. Failures (rate limits, blocks) resolve in milliseconds and don't slow things down. web_search resolves as soon as MIN_SUCCESS (default 2) instances return results; news_search and image_search resolve as soon as 1 instance responds.

Self-learning instance selection

The first search discovers which public instances accept requests from your IP and saves them to ~/.freesearch-mcp-cache.json. All subsequent searches go straight to the proven instances — no re-discovery needed.

Instance ranking uses data from searx.space: latency (50%) + uptime (30%) + engine count (20%).

Reciprocal Rank Fusion

web_search merges results from multiple instances: each result earns 1 / (position + 1) points per instance, scores are summed, and URLs are normalized and deduplicated before returning. Results that appear across multiple instances and rank near the top of each naturally score highest.

Content extraction

extract_page uses Mozilla's Readability to strip navigation, ads, and boilerplate from any page, then converts the article content to clean markdown via Turndown. Extracted pages are cached in-process for 30 minutes.

---

Configuration

All settings are optional environment variables:

Variable	Default	Description
SEARXNG_URL	—	Pin a specific SearXNG instance. Bypasses all auto-discovery. Ideal for self-hosted setups.
MAX_INSTANCES	999	Maximum number of instances tried per search
MIN_SUCCESS	2	Instances that must return results before web_search resolves
MAX_WAIT_MS	5000	Maximum time (ms) to wait for instances per search
SEARCH_TIMEOUT_MS	4000	Per-instance HTTP timeout
CACHE_TTL_MS	300000	How long to cache search results in memory (5 min). Does not affect extract_page, which uses a fixed 30-minute cache.
INSTANCE_CACHE_TTL_MS	3600000	How long to cache the ranked instance list in memory (1 h)

Self-hosted SearXNG

For reliable use from servers or CI environments (where public instances may rate-limit), run your own SearXNG:

docker run -d -p 8080:8080 searxng/searxng

Then pin it:

{ "mcpServers": { "freesearch": { "command": "npx", "args": ["-y", "freesearch-mcp"], "env": { "SEARXNG_URL": "http://localhost:8080" } } } }

---

Performance

Scenario	Speed
First search (cold)	2–5 s (discovers working instances)
Subsequent searches	1–3 s
Cached result (repeat query)	< 50 ms
After restart	Fast (instance list persisted to disk for 24 h)

---

License

MIT