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

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

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