🔍 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 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_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_in

…

Searxng

Installation

Configuration

How to use

README