🔍 SearXNG MCP Server

Privacy-respecting web search for AI assistants — use an operator-controlled or trusted SearXNG instance with Claude, Cursor, and more.

An MCP server that integrates the SearXNG API, giving AI assistants web search capabilities.

✨ Featured in the GitHub MCP Registry.

Quick Start

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Replace YOUR_SEARXNG_INSTANCE_URL with the URL of your SearXNG instance (e.g. https://searxng.example.com). You can also provide interchangeable replicas as a semicolon-separated list, e.g. https://one.example.com;https://two.example.com.

For verified Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, Windsurf, Cline, and OpenCode recipes, see the MCP client configuration cookbook.

For a bounded, client-neutral method to search, inspect sources, cross-check claims, and cite evidence, see the evidence-focused research workflow.

For measured MCP-process CPU and memory starting points, see measured deployment profiles.

Features

• Web Search: General, news, and article queries with pagination, time-range/language/safe-search filters, relevance filtering (min_score), and formatted-text or raw-JSON output selected per call (response_format) or with the operator default (SEARXNG_DEFAULT_RESPONSE_FORMAT).

• Instance Failover & Fan-out: Configure interchangeable SearXNG replicas in SEARXNG_URL; searches fail over in order by default, or query all healthy replicas in parallel and merge results with SEARXNG_FANOUT.

• Direct Answers & Metadata: Text results surface SearXNG answers, corrections, suggestions, and infoboxes before the result list.

• Search Suggestions: Query autocomplete via SearXNG's /autocompleter endpoint.

• Instance Capability Discovery: Inspect configured categories, engines, defaults, locales, and plugins from /config.

• URL Content Reading: Content-type-aware Markdown conversion, including bounded PDF text extraction, with pagination, section filtering, paragraph ranges, and heading extraction.

• Browser Solver Support: For each uncached URL that passes static URL validation and the HEAD size preflight, optionally acquire a browser session from FlareSolverr, Byparr, or both, then replay the returned user-agent and scoped cookies through the bounded URL reader. In dual-provider mode FlareSolverr is always primary and Byparr is attempted only after a busy or transient-unavailable primary. FlareSolverr 3.5.0 and Byparr 2.1.0 were verified on 2026-07-30.

• Intelligent Caching: Both search results and URL content are cached in memory with configurable TTL and least-frequently-used (LFU) eviction, reducing redundant requests.

• SSRF Protection: web_url_read blocks private/internal URLs and redirects by default in all transport modes.

• HTTP Transport: Optional MCP SDK v2 Streamable HTTP mode with opt-in hardening, rate limiting, and bounded stateless compatibility for serverless or horizontally scaled deployments. Modern 2026-07-28 requests and retained legacy clients share the same tool and resource surface.

• HTML Fallback: Optionally parse results from the HTML page for public instances that reject format=json.

• Lite Tools Mode: Minimal tool schemas for local models with small context windows.

• Proxy Support: Global or per-tool HTTP/HTTPS proxies for search and URL-reader traffic.

The verified linux/amd64 images came from multi-architecture manifests ghcr.io/flaresolverr/flaresolverr:v3.5.0@sha256:139dfee1c6f89249c8d665d1333a42e8ec74ec0a86bc6bb1c8461e10d3a66a47 and ghcr.io/thephaseless/byparr:2.1.0@sha256:01a46a2865d9a6db5eb8ead04ec0dd33b8fbe233e8565ae70b50d4cc0af4cfb0. Client cancellation stops local work promptly, but a remote browser may continue until its configured provider timeout after the HTTP client disconnects. See browser solver verification.

Why mcp-searxng?

As of 2026-07-29, the capability comparison below reflects the official Brave MCP, Exa MCP, and Firecrawl MCP projects. “Pagination” means an exposed page or offset control. “Self-hosted” means the search service can run under your control. “Free / No API key” means this MCP server does not require a paid search-vendor API key; you still operate or select the underlying SearXNG instance.

Brave MCP Exa MCP Firecrawl MCP mcp-searxng

Web Search ✓ ✓ ✓ ✓

Read URL ✗ ✓ ✓ ✓

Pagination ✓ ✗ ✓ ✓

Self-hosted ✗ ✗ Partial ✓

Free / No API key ✗ ✗ ✗ ✓

Privacy depends on the SearXNG deployment. An operator-controlled instance can avoid trusting a third-party search operator, while a public instance receives the query and may log it. SearXNG and this MCP integration do not by themselves provide anonymity.

How It Works

mcp-searxng is a standalone MCP server — a separate Node.js process that your AI assistant connects to for web search. It queries one SearXNG instance, or a semicolon-separated list of interchangeable SearXNG replicas, via the HTTP JSON API.

Not a SearXNG plugin: This project cannot be installed as a native SearXNG plugin. Point it at any existing SearXNG instance, or interchangeable replica list, by setting SEARXNG_URL.

AI Assistant (e.g. Claude)
        │  MCP protocol
        ▼
  mcp-searxng  (this project — Node.js process)
        │  HTTP JSON API  (SEARXNG_URL)
        ▼
  SearXNG instance(s)

For SearXNG deployment, configuration, and troubleshooting, see Operating Self-Hosted SearXNG with mcp-searxng.

Tools

• searxng_web_search

• Execute web searches with pagination

• Inputs:

• query (string): The search query. This string is passed to external search services.

• pageno (number, optional): Search page number, starts at 1 (default 1)

• time_range (string, optional): Filter results by time range - one of: "day", "week", "month", "year" (default: none)

• language (string, optional): Language code for results (e.g., "en", "fr", "de") or "all" (default: "all")

• safesearch (string enum, optional): Safe search filter level, one of "0" (None), "1" (Moderate), or "2" (Strict). Legacy numeric values 0, 1, and 2 are still accepted for backward compatibility. (default: instance setting)

• min_score (number, optional): Minimum relevance score from 0.0 to 1.0. Results below this score are filtered out.

• num_results (number, optional): Maximum number of results to return, from 1 to 20. SEARXNG_MAX_RESULTS applies as an operator ceiling.

• categories (string, optional): Comma-separated SearXNG categories (e.g. "news", "it,science"). Live /config capabilities are aggregated across reachable instances; prefer searxng_instance_info categories.common for consistent multi-instance results. Known values are trimmed and normalized case-insensitively; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If /config is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default.

• engines (string, optional): Comma-separated SearXNG engine names (e.g. "google,bing,ddg", "semantic scholar"). Live /config capabilities are aggregated across reachable instances; prefer searxng_instance_info engines.common.enabled for consistent multi-instance results. Known values are trimmed and normalized case-insensitively, including engines disabled by default; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If /config is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default.

• response_format (string, optional): Response format, either "text" for formatted agent-readable output or "json" for raw SearXNG JSON with filtered/sliced results. If omitted, `SEARXNG_DEFAULT_RESPONSE_FOR