🔍 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

You need an existing SearXNG instance with JSON search enabled. This project connects an MCP client to SearXNG; it does not install SearXNG. Use an instance you operate or trust. Start with the self-hosted or public-instance guide if needed.

Choose how to connect:

For clients using mcpServers JSON (such as Claude Desktop), add:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": { "SEARXNG_URL": "https://search.example.com" }
    }
  }
}

Replace the example URL with your SearXNG base URL. Other clients use different configuration shapes: choose your client recipe. Leave MCP_HTTP_PORT unset for local STDIO. Docker also needs environment forwarding into the container.

Reload the client, inspect its MCP tool inventory, then ask it to search for SearXNG documentation. A simple tool call is searxng_web_search with {"query":"SearXNG"}. Discovery alone does not test SearXNG connectivity. If the call fails, start with troubleshooting.

Features

• Search with pagination, filters, direct answers and full or compact text/JSON output.
• Read HTML, structured text and bounded PDF text; inspect headings or selected sections.
• Discover instance capabilities and get query suggestions.
• Optional replica failover/fan-out, HTML fallback, caching, proxies and browser solvers.
• Local STDIO or Streamable HTTP, with static bearer and optional OAuth protection.

See the tool guide for capabilities and limits, configuration reference for settings, and historical deployment measurements for bounded resource-planning evidence.

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.

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 client → mcp-searxng → SearXNG → search engines

The client either starts its own STDIO process or connects to an HTTP service. SEARXNG_URL identifies the SearXNG service, not the MCP endpoint. URL reading fetches the selected website directly. A semicolon-separated replica list is supported for interchangeable SearXNG deployments; see replica configuration.

STDIO is the default. Legacy Streamable HTTP sessions are stateful by default: clients should send DELETE /mcp when finished, then reinitialize if a later request receives HTTP 404 for the terminated session. Modern HTTP requests and the MCP_HTTP_STATELESS=true legacy mode are sessionless; see HTTP transport configuration.

Tools

The tool guide contains examples and the full parameter reference. The optional research workflow explains how to inspect sources and cite evidence.

Installation

For NPX and npm installs, Node.js 22 or later is required. The Docker image includes its Node.js runtime.

npm install -g mcp-searxng

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Pre-built image:

docker pull isokoliuk/mcp-searxng:latest

Image signatures can be verified with Cosign — see SECURITY.md for instructions.

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

To pass additional env vars, add -e VAR_NAME to args and the variable to env. For browser-solver integration, pass FLARESOLVERR_URL, BYPARR_URL, or both and make the configured services reachable from this container. Dual mode has a fixed FlareSolverr-first order and no automatic reverse failover. Safe rendered HTML and explicit Byparr PDF content are read directly; ambiguous content uses guarded replay, with bounded failover for eligible read failures. See URL Reader Controls for the complete behavior and Docker Compose example.

Build locally:

docker build -t mcp-searxng:latest -f Dockerfile .

Use the same config above, replacing isokoliuk/mcp-searxng:latest with mcp-searxng:latest.

docker-compose.yml:

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=${SEARXNG_URL:?Set SEARXNG_URL in the environment}
      # Add optional variables as needed — see CONFIGURATION.md

The tracked Compose file is intentionally STDIO-only and publishes no network ports; MCP clients launch it with an absolute Compose-file path and docker compose run --rm -T, not docker compose up. The -T flag prevents pseudo-TTY allocation so MCP JSON-RPC stays on raw standard input and output. Compose fails before launch unless the MCP client supplies SEARXNG_URL.

MCP client config:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/docker-compose.yml",
        "run", "--rm", "-T", "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_