Skip to content
MCP Shelf

SearXNG MCP Server

Web search through your own SearXNG instance: no vendor, no API key.

View on GitHub
  • Started in our test
  • ★ 1.3K GitHub stars
  • Last commit 27 Oct 2026

What is SearXNG?

SearXNG MCP is an open-source MCP server that gives AI assistants web search and page reading through a SearXNG instance, so no search API key or vendor account is needed.

Tools
4
Runs on
Your computer
Licence
MIT
GitHub stars
1.3K

Good for

  • Search without sending queries to a search vendor
  • Local or air-gapped setups
  • Avoiding per-query costs

You'll need

  • A running SearXNG instance with JSON output enabled
  • Node.js 22 or newer, or Docker

Started in our testWe ran this exact config on 26 Oct 2026: it started and answered with 4 tools.

MCP Shelf take

We started SearXNG on our own test machine on 26 Oct 2026 and it answered with 4 tools. All 4 only read, so it cannot change anything on its own. Every tool comes with a useful description, all of them say whether they change things, and the tool list costs about 700 tokens of context before you ask a thing. It sits 13th of 13 in its category on our shelf by GitHub stars (1.3K).
MCP Shelf tests: numbers from our own runs, not the README · tested on 26 Oct 2026

What can SearXNG read and change?

It can read

  • Search results from the engines your SearXNG instance queries
  • Any web page or PDF the agent asks to read, fetched directly from that site

It can change

  • Nothing. It only searches and reads.

Safer setup: Run your own SearXNG instance. A public one sees and may log every query you send.

SearXNG in more detail

SearXNG is an open-source metasearch engine you host yourself. This server points your assistant at it, so searches go through your instance rather than a commercial search API, and it can fetch a result page as Markdown.

If you do not already run SearXNG, a commercial option like Exa is less work.

Made by
Ihor Sokoliuk and contributors
Latest version
2.8.1 (25 Oct 2026)
npm package
mcp-searxng
Last commit
27 Oct 2026
Setup checked
27 Oct 2026
Page updated
27 Oct 2026

What's in the pod

What tools does SearXNG have?

We found 4 tools when we started it on 26 Oct 2026. Every one of them only reads, so nothing changes unless you act on what it finds.

Only reads4 tools · Looks things up and changes nothing.

ToolWhat it is for
searxng_instance_infoAsks your SearXNG instance which engines, categories and defaults it offers.
searxng_search_suggestionsFetches autocomplete ideas to sharpen a vague query before searching.
searxng_web_searchRuns a search through your SearXNG instance and returns titles, links and snippets, with paging and filters.
web_url_readOpens a web page or PDF and returns readable text, or just the headings or section you ask for.

Grouped and described by us. The README on GitHub lists the inputs each tool takes.

How clearly it describes its tools to your assistant

Tools with a description
4 of 4
Say if they change things
4 of 4
Context it takes, at least
~700 tokens

Every tool says whether it only reads or can change things, so a client can ask before the risky ones.

From the tool list it sent us. The token figure counts names, descriptions and input names; the full schemas your client loads add more.

How do I install SearXNG?

Install steps from the SearXNG README

The project's own instructions, copied from its README on GitHub on 27 Oct 2026 under its MIT licence. They are the source of truth; the ready-made configs further down are built from them. The rest of the README is in the README tab.

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:

Your setup Start here
Client starts the server locally Install Node.js 22 or later, then use the NPX example below or your client recipe.
Client starts a Docker container Use the Docker/STDIO recipe in Installation.
You have an independently running HTTP service Use your client's HTTP recipe with the full /mcp URL.
You need to operate an HTTP service Follow the HTTP server guide.

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.

What you need first

  • A running SearXNG instance with JSON output enabled
  • Node.js 22 or newer, or Docker

Add SearXNG to your app

Pick your app for a ready-to-paste snippet and where it goes, built from the steps above.

Where it goes: Your terminal

Claude Code
claude mcp add --scope user --env SEARXNG_URL=http://localhost:8080 --transport stdio searxng -- npx -y mcp-searxng

Swap in your instance's address. Check it with claude mcp get searxng, then /mcp inside Claude Code.

Checked against the project's own install docs on 27 Oct 2026: ihor-sokoliuk/mcp-searxng README, github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/client-configurations.md.

Did this work for you?

Projects change their install steps often. If SearXNG did not install, or something here no longer matches the project, tell us and we will check it against the README and fix the page.

New to this? See the setup guides for Claude Code, Cursor, Claude Desktop, VS Code, Codex and ChatGPT. If it will not start, test it in MCP Inspector and look up the error in Fixing MCP server errors.

SearXNG not working? Common fixes

403 Forbidden from SearXNG
The instance has JSON output turned off or blocks API calls. Enable json under search formats in its settings.yml, or switch on SEARXNG_HTML_FALLBACK.
The tools show up but every search fails
Check SEARXNG_URL points at the SearXNG site itself, not at an MCP address, and that you can reach it from the same machine.
npx fails to start
It needs Node.js 22 or newer. Docker is an alternative that bundles its own Node.
Results are thin or stale
Ask searxng_instance_info which engines are enabled and turn more on in your instance.

How do I configure SearXNG?

Names are exactly as the project spells them. Required ones are marked.

SettingWhat it does
SEARXNG_URLEnvironment variable · requiredBase address of the SearXNG instance to search through. Separate several with semicolons for failover.https://search.example.com
SEARXNG_HTML_FALLBACKEnvironment variableSet to true to scrape the HTML results page when the instance refuses JSON. Best effort only.true
MCP_HTTP_PORTEnvironment variableSet it to serve over HTTP on that port. Leave it unset for the normal local setup.8080
MCP_HTTP_HOSTEnvironment variableAddress the HTTP server binds to.
MCP_HTTP_STATELESSEnvironment variableSet to true to run HTTP without sessions, for load-balanced setups.

SearXNG FAQ

How do I add SearXNG MCP to Claude Code?

With Node.js 22 or later, run claude mcp add --scope user --env SEARXNG_URL=http://localhost:8080 --transport stdio searxng -- npx -y mcp-searxng, using your own instance's address. The project also documents a Docker version with the isokoliuk/mcp-searxng image.

Does SearXNG MCP include a search engine?

No. It connects your assistant to a SearXNG instance that you run or trust, and SearXNG in turn queries engines such as Google, Bing and DuckDuckGo. The instance must have JSON output switched on.

Is SearXNG MCP free?

Yes. The server is MIT licensed and SearXNG is free software, so there is no API key or per-search bill, which is its main draw over Brave, Exa or Firecrawl.

Why does SearXNG MCP get 403 Forbidden?

Usually the instance has JSON output turned off, or an access-control layer in front of it refused the request. On your own instance, add json to the search formats in settings.yml. If you cannot, SEARXNG_HTML_FALLBACK=true lets the server parse the HTML results page instead, with less detail.

Is SearXNG MCP private?

Only as private as the instance. Your own instance keeps queries with you, though it still forwards them to the search engines it uses; a public instance's operator can see and log what you search.

Can SearXNG MCP read web pages and PDFs?

Yes. Besides searching, its URL reading tool fetches a page or PDF and returns a bounded amount of its text, so the assistant can follow up on a result.

Does SearXNG MCP work with ChatGPT?

Only if you run it as an HTTP service on a public address, which the project's HTTP server guide covers, and protect it with a token. For most people a desktop client running it locally is simpler and safer.

SearXNG MCP or DuckDuckGo MCP?

DuckDuckGo MCP needs nothing set up but relies on one engine and can be rate limited. SearXNG MCP needs an instance to talk to, but blends several engines and puts you in control of privacy and limits.

SearXNG README

This is the project's own README from ihor-sokoliuk/mcp-searxng, written by Ihor Sokoliuk and contributors, and shared under its MIT licence. We copied it on 27 Oct 2026, so the version on GitHub may be newer.

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

Your setup Start here
Client starts the server locally Install Node.js 22 or later, then use the NPX example below or your client recipe.
Client starts a Docker container Use the Docker/STDIO recipe in Installation.
You have an independently running HTTP service Use your client's HTTP recipe with the full /mcp URL.
You need to operate an HTTP service Follow the HTTP server guide.

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?

Capability comparison recorded on 2026-07-29

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

Tool Use it to
searxng_web_search Find sources and refine results
searxng_search_suggestions Complete or refine a query
searxng_instance_info Inspect categories, engines and defaults
web_url_read Read a known URL as text/Markdown

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

Installation

The project-maintained distribution methods are npm (including npx) and Docker. Additional package formats, including Nix, can be maintained separately by the community.

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

NPM (global install)
npm install -g mcp-searxng
{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}
Docker

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

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.

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

Symptom Next check
Server absent or disconnected Client/process startup
HTTP auth, session or proxy error HTTP connection
Tools appear but search fails SearXNG connection
Empty, poor or stale results Filters, upstream metadata and cache
URL/PDF failure or timeout URL reading
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

Configure search for useful coverage with tested upstream settings, specialist engine routes and MCP output controls. The deployment recipe includes a private Compose stack and optional browser providers, with dated results and known failures.

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.

Two peas, one chat

Chat with AI about SearXNG

Opens a chat primed with SearXNG’s README and setup docs from this page, or add it in Cursor to use its tools.

The Cursor button opens Cursor and asks before it adds the server. Fill in any keys it needs in Cursor’s MCP settings.

Peas in a pod

What are the alternatives to SearXNG?

How SearXNG lines up against its neighbours on the shelf. See every browser and web data server.

  • SearXNGThis pea

    Web search through your own SearXNG instance: no vendor, no API key.

    Tools
    4
    Runs on
    Your computer
    Licence
    MIT
    Stars
    1.3K
  • Apify

    Find and run ready-made Apify scrapers for maps, social media, shops and search.

    Tools
    10
    Runs on
    Hosted or your computer
    Licence
    MIT
    Stars
    13.6K
  • BrowserTools MCP

    Console logs, network calls, screenshots and Lighthouse audits from your own Chrome tab.

    Tools
    16
    Runs on
    Your computer
    Licence
    MIT
    Stars
    7.3K
  • ExecuteAutomation Playwright MCP

    A community Playwright server that also writes test code and emulates phones and tablets.

    Tools
    33
    Runs on
    Your computer
    Licence
    MIT
    Stars
    5.7K
  • Wigolo

    Search, fetch, crawl and extract the web locally, with no keys or metered bill.

    Tools
    10
    Runs on
    Your computer
    Licence
    AGPL-3.0-only
    Stars
    5.5K
  • Perplexity MCP

    Perplexity's search, answers and deep research, from Perplexity itself.

    Tools
    4
    Runs on
    Hosted or your computer
    Licence
    MIT
    Stars
    2.6K

Compared head to head: Exa vs SearXNG.

Full docs on GitHubihor-sokoliuk/mcp-searxng

Something wrong on this page? Tell us.

For bots & AI agents

Machine-readable versions of SearXNG and MCP Shelf. Fetch these instead of parsing this page.

This listing (.md)llms.txtllms-full.txtai.txtFull catalog (.md)API specMCP serverMCP manifestDeveloper docs