🔍 SearXNG MCP Server

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?

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.

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

docker pull isokoliuk/mcp-searxng:latest

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

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

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

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

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

HTTP Transport

Run HTTP independently, then connect the client. See the
HTTP server guide for local checks, static bearer
authentication, OAuth requirements and deployment verification.

Configuration

For the default local setup, SEARXNG_URL is the required setting. Optional
modes such as hardened HTTP and OAuth have companion requirements. Use the
configuration reference for environment variables,
defaults, caching, timeouts, proxies, TLS, and limits.

Optional MCP OAuth

An HTTP deployment can use OAuth with an external authorization provider.
See authentication choices.
Static bearer authentication and SearXNG Basic Auth protect different connections.

Troubleshooting

403 Forbidden from SearXNG

JSON output may be disabled, or an access-control layer may have denied the
request. Follow the direct checks
before changing settings. A working browser page does not prove the JSON API works.

Can't enable JSON? (HTML fallback)

SEARXNG_HTML_FALLBACK=true can retry 403/404/non-JSON search responses as HTML.
Parsing is best-effort and metadata is limited; compact output omits fallback
markers. Read the public-instance guidance
before enabling it on a service you do not control.

For a bug report, collect a minimal reproduction and relevant errors.

Documentation

Find a guide by task. These links open current main-branch
documentation. Unreleased behavior is labeled; consult the matching Git tag
when investigating an older version.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE for details.