searxng-mcp

A Model Context Protocol server that gives any MCP-capable agent (Claude Desktop, AiderDesk, OpenCode, Goose, …) web search and page reading through a self-hosted SearXNG instance — no API key, no per-query metering, and your queries never leave your network before SearXNG fans them out.

Built as a drop-in replacement after two metered search-API keys ran out of quota on the same day.

Tools

Behaviour worth knowing:

• Silent-zero detection. SearXNG returns HTTP 200 with an empty result list when its upstream engines are CAPTCHA-blocked or rate-limited. The server treats that as a miss and retries through fallback engine sets (bing,yandex → google,duckduckgo,brave,startpage → mojeek,wikipedia,wiby) before returning, and reports which set answered.

• Engine names are category-specific in SearXNG (bing vs bing news); the server picks the right defaults per category.

• Extraction refuses non-text content types and pages over 3 MB, and truncates at a configurable character limit with an explicit marker.

Related MCP server: local-web-search-service

Setup

You need a SearXNG instance with the JSON format enabled (search.formats: [html, json] in settings.yml). The quickest way is the official Docker image on port 8080.

npm install
SEARXNG_URL=http://your-searxng:8080 node server.mjs

Register it with your MCP client (stdio transport):

{
  "mcpServers": {
    "searxng": {
      "command": "node",
      "args": ["/path/to/searxng-mcp/server.mjs"],
      "env": { "SEARXNG_URL": "http://your-searxng:8080" }
    }
  }
}

Environment

Smoke test

npm test          # spawns the server over stdio and exercises all four tools against your instance

License

MIT — see LICENSE.