SearXNG MCP

Requires Node.js 20 or later.

<details>

<summary>NPM (global install)</summary>

npm install -g mcp-searxng

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

</details>

<details>

<summary>Docker</summary>

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

</details>

<details>

<summary>Docker Compose</summary>

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_URL"
      }
    }
  }
}

If you previously used the tracked file as an HTTP service on port 8080, put the HTTP settings in an untracked docker-compose.override.yml:

services:
  mcp-searxng:
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - MCP_HTTP_PORT=8080
      - MCP_HTTP_HOST=0.0.0.0

Here 0.0.0.0 is the container-side bind address; the host-side port remains loopback-only. This override has no authentication and is only a temporary single-host migration path. Before adding co-located containers or exposing the service beyond the local machine, follow the hardened deployment guidance.

</details>

<details>

<summary>HTTP Transport</summary>

By default the server uses STDIO, launched by your MCP client. To use HTTP instead, run mcp-searxng as a standalone process with MCP_HTTP_PORT set. In this mode it serves the MCP protocol over HTTP and does not speak STDIO, so your client connects to it by URL rather than spawning it.

Start the server:

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng

Or with Docker (bind to all interfaces so the port is reachable from the host):

docker run --rm -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  -e MCP_HTTP_PORT=3000 -e MCP_HTTP_HOST=0.0.0.0 \
  -e SEARXNG_URL=http://host.docker.internal:8080 \
  isokoliuk/mcp-searxng:latest

The --add-host mapping lets the container reach a SearXNG instance on the host via host.docker.internal; it resolves automatically on Docker Desktop but needs this flag on native Linux. Point SEARXNG_URL at your actual instance if it runs elsewhere.

Connect an HTTP-capable MCP client to the /mcp endpoint by URL:

{
  "mcpServers": {
    "searxng-http": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Endpoints: POST/GET/DELETE /mcp (stateful MCP protocol), GET /health (health check)

Stateful sessions remain the default. Set MCP_HTTP_STATELESS=true when a deployment cannot preserve in-memory sessions between requests. Every stateless POST creates a fresh MCP server and transport, ignores any incoming session ID, and returns negotiated JSON or an SSE stream within that same POST. Stateless mode is POST-only: GET /mcp and DELETE /mcp return HTTP 405 with Allow: POST, and no cross-request subscriptions, resumability, or server-to-client notifications are preserved.

Stateless requests are bounded by global and per-client-IP in-flight limits plus a request lifetime. See CONFIGURATION.md for defaults, overload and timeout responses, proxy-aware fairness, and the complete compatibility contract.

Test it:

curl http://localhost:3000/health

The server binds to 127.0.0.1 by default; set MCP_HTTP_HOST=0.0.0.0 for remote or containerized deployments. Before exposing it on a network, enable hardened mode (MCP_HTTP_HARDEN) and see CONFIGURATION.md for MCP_HTTP_TRUST_PROXY so rate limiting and logs use the correct client IP.

</details>