<div align="center">

🔍 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.

</div>

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 Streamable HTTP mode with opt-in hardening, rate limiting, and bounded stateless compatibility for serverless or horizontally scaled deployments.
• 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_FORMAT applies; if unset or invalid, text is used. An explicit response_format always takes precedence.
    • result_detail (string, optional): "full" (the default) preserves SearXNG metadata, warnings, provenance, answers, infoboxes, corrections, and suggestions. "compact" returns only title, URL, and the description/content snippet for every result; compact JSON uses exactly the title, url, and content keys. Use full when those research signals matter.
    • Clients that explicitly send or auto-inject response_format=text continue to override the operator default. If omitted calls still return text after configuring JSON, inspect the arguments emitted by the MCP client.

  Migration: compact text has exactly three lines per result and no cache annotation or preamble. Update line parsers that expect relevance scores or search metadata to request result_detail="full" (or accept compact's three-line records).

  Compact deliberately suppresses warnings, provenance, and every other search signal. Full text may add valid optional lines in fixed order: score, engines, category, published date, thumbnail, image source; invalid optional metadata is omitted. Text fields are normalized to single lines. SEARXNG_MAX_RESULT_CHARS truncates result content in compact and full text/JSON responses, including full JSON for existing users who already set the variable; compact text normalizes line separators before applying the cap, while JSON caps the original string value.

  With SEARXNG_LITE_TOOLS=true, the Lite schema stays query-only, but explicitly supplied optional overrides such as response_format and result_detail are still validated and honored.

• searxng_search_suggestions

  • Get autocomplete suggestions for refining search queries
  • Inputs:
    • query (string): Partial or complete query to autocomplete.
    • language (string, optional): Language code for suggestions (e.g., "en", "fr", "de") or "all" (default: "all")

• searxng_instance_info

  • Discover categories aggregated from reachable configured SearXNG instances, optionally inc