SearXNG Public MCP Server with Fallback Support

Overview

This MCP (Model Context Protocol) server provides a stable, MCP-compatible endpoint that queries a pool of public SearXNG instances and automatically falls back to alternates when an instance is unreachable or returns errors. Because many public SearXNG deployments are ephemeral, rate-limited, or inconsistently reachable, the server abstracts a list of targets behind a single reliable interface so tools, agents, or applications can perform web searches without having to manage multiple instance health checks themselves.

The server acts as a proxy and scheduler: it accepts incoming MCP-style requests for search, routes the query to a chosen SearXNG instance, and if that instance fails it transparently retries against configured fallback instances. It returns normalized JSON search results and basic metadata so consumers (LLM agents, search tools, monitoring systems) can integrate search results into larger pipelines without dealing with individual instance variability.

Features

• MCP-compatible server endpoint that proxies search queries to public SearXNG instances
• Automatic fallback across a configurable pool of SearXNG hosts
• Health-aware routing and retry logic to avoid known-bad instances
• JSON normalization of search results for consistent downstream consumption
• Configurable timeouts, concurrency limits, and per-instance weights
• Deployable via Docker / Docker Compose or as a standalone binary/service
• Simple HTTP API suitable for use by LLM agents, tool registries, and automation scripts

Installation / Configuration

Minimum requirements: Go runtime or the prebuilt binary (if provided in the repo), or Docker for containerized deployment. Clone the repository to build locally:

git clone https://github.com/pwilkin/mcp-searxng-public.git
cd mcp-searxng-public
# build (if a Go project)
go build ./cmd/mcp-searxng-public

Example Docker Compose (recommended for quick start):

version: "3.8"
services:
  mcp-searxng-public:
    image: pwilkin/mcp-searxng-public:latest
    ports:
      - "8080:8080"
    environment:
      - LISTEN_ADDR=0.0.0.0:8080
      - INSTANCE_LIST=/data/instances.txt
      - REQUEST_TIMEOUT=10s
      - MAX_RETRIES=3
    volumes:
      - ./instances.txt:/data/instances.txt:ro

Simple instances file (one SearXNG base URL per line):

https://searx.example.one
https://searx.example.two
https://searx.example.three

Suggested environment/configuration options (adjust per deployment):

You can also run the binary directly and pass flags or an alternate config file (if the project supports it):

./mcp-searxng-public \
  --listen-addr=0.0.0.0:8080 \
  --instance-list=./instances.txt \
  --request-timeout=10s \
  --max-retries=3

Available Resources

The server exposes a lightweight HTTP API compatible with MCP tool expectations. Typical resources available:

• /search (POST/GET) — Accepts a query and returns normalized search results
• /health — Basic health check for uptime and pool status
• /instances — (optional) lists configured instances and their health state

A minimal search request (POST with JSON) might look like:

curl -sS -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"q":"privacy focused search engines","lang":"en"}'

Response format (normalized JSON):

{
  "query": "privacy focused search engines",
  "engine": "searxng-public-proxy",
  "results": [
    {
      "title": "DuckDuckGo — Privacy, simplified",
      "url": "https://duckduckgo.com",
      "snippet": "DuckDuckGo is the search engine that doesn’t track you.",
      "source": "sometarget.example"
    },
    ...
  ],
  "meta": {
    "used_instance": "https://searx.example.two",
    "status": "ok"
  }
}

Note: exact endpoint names and response shape may differ; consult the repository for the definitive contract if you require strict typing.

Use Cases

• Integrating web search into an LLM agent: register the MCP server as a “search” tool so the agent can call out for up-to-date web context. The server hides instance churn and presents consistent results to the agent.
• Batch scraping/monitoring: run repeated queries across topics without maintaining a custom pool of SearXNG hosts; the server retries and spreads load across healthy instances.
• Quick prototyping: developers building search-aware apps can rely on the server instead of configuring and maintaining a single SearXNG deployment, speeding iteration.
• Fault-tolerant tooling: embed the MCP endpoint in pipelines that require high availability for search data; the fallback logic reduces downtime caused by single-instance failures.

Concrete example — register as a tool in an agent tool registry:

{
  "name": "searxng_public_search",
  "type": "mcp",
  "url": "http://mcp-searxng-public.local:8080/search",
  "description": "Search web content via pooled public SearXNG instances"
}

Then an agent can POST queries and consume the normalized JSON results, trusting the MCP server to handle retries and health checks.

Best practices & tips

• Maintain a curated list of reliable instances in the instances file and rotate out ones that consistently fail.
• Use conservative timeouts and small max-retries to avoid long blocking requests in latency-sensitive flows.
• Monitor the /health and /instances endpoints with your existing observability tooling to detect when fallback rates increase.
• Respect the usage policies of individual public SearXNG deployments — spread load and avoid aggressive polling.

Repository and source code: https://github.com/pwilkin/mcp-searxng-public