---
title: "SearXNG MCP Server: Private, Self-Hosted Web Search for AI"
url: "https://mcpshelf.co/servers/searxng"
description: "Point your assistant at your own SearXNG instance for web search with no API key or search vendor. Config, the one variable it needs, our test."
updated: "2026-10-27"
site: "MCP Shelf"
---

# SearXNG

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

Source: https://mcpshelf.co/servers/searxng  
Markdown: https://mcpshelf.co/servers/searxng.md  
Generated: 2026-11-22T18:14:34.296Z

## Facts

- **Name:** SearXNG
- **Tagline:** Web search through your own SearXNG instance: no vendor, no API key.
- **Description:** 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.
- **Repository:** https://github.com/ihor-sokoliuk/mcp-searxng
- **Package:** mcp-searxng 2.8.1 (npm)
- **Install:** `claude mcp add --scope user --env SEARXNG_URL=http://localhost:8080 --transport stdio searxng -- npx -y mcp-searxng`
- **Transport:** stdio (local)
- **Auth:** Needs `SEARXNG_URL`
- **Tools exposed:** 4: `searxng_web_search`, `searxng_search_suggestions`, `searxng_instance_info`, `web_url_read`
- **Category:** Browser and web data (https://mcpshelf.co/categories/browser-and-web)
- **Stats:** 1.3K GitHub stars, last commit 27 Oct 2026, 0 upvotes on MCP Shelf
- **Install check:** Started in our test
- **Listed:** 2026-10-26
- **Page updated:** 2026-10-27

## Full description

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

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 |
| GitHub | https://github.com/ihor-sokoliuk/mcp-searxng |
| Licence | MIT |
| npm package | [mcp-searxng](https://www.npmjs.com/package/mcp-searxng) 2.8.1 (25 Oct 2026) |
| GitHub stars | 1.3K |
| Last commit | 27 Oct 2026 |
| Tools | 4 |
| Runs on | Your computer |
| Install check | Started in our test |
| Category | [Browser and web data](https://mcpshelf.co/categories/browser-and-web) |
| Works with | Claude Code, Cursor, Claude Desktop, VS Code, Codex, Windsurf |
| Setup checked | 27 Oct 2026 |
| Page updated | 27 Oct 2026 |

**Our check:** We ran this exact config on 26 Oct 2026: it started and answered with 4 tools.

#### Try asking SearXNG

- "Search for the latest Node.js LTS release notes and summarise what changed."
- "Find three tutorials on setting up Postgres logical replication."
- "Read this page and pull out the install steps: https://example.com/docs"

#### 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), tested on 26 Oct 2026

### What tools does SearXNG have?

We listed 4 tools on 26 Oct 2026. Every one of them only reads.

| Tool | Kind | What it is for |
| --- | --- | --- |
| `searxng_web_search` | reads | Runs a search through your SearXNG instance and returns titles, links and snippets, with paging and filters. |
| `searxng_search_suggestions` | reads | Fetches autocomplete ideas to sharpen a vague query before searching. |
| `searxng_instance_info` | reads | Asks your SearXNG instance which engines, categories and defaults it offers. |
| `web_url_read` | reads | Opens a web page or PDF and returns readable text, or just the headings or section you ask for. |

#### How clearly it describes its tools

4 of 4 tools have a description and 4 of 4 say whether they change things. The tool list takes at least ~700 tokens of context. Every tool says whether it only reads or can change things, so a client can ask before the risky ones.

### How do I install SearXNG?

#### Install steps from the SearXNG README

Copied from the project's [README on GitHub](https://github.com/ihor-sokoliuk/mcp-searxng#readme) on 10 Nov 2026 under its MIT licence.

##### 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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/self-hosted-searxng.md)
or [public-instance](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/public-searxng-instances.md) 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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/http-server.md). |

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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/client-configurations.md).
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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md).

#### What you need first

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

#### Claude Code

Where: Your terminal

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

#### Cursor

Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

```json
{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}
```

#### Claude Desktop

Where: claude_desktop_config.json (Settings → Developer → Edit Config)

```json
{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}
```

#### VS Code

Where: .vscode/mcp.json in your project

```json
{
  "servers": {
    "searxng": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}
```

#### Codex

Where: ~/.codex/config.toml, shared by the Codex CLI, IDE extension and ChatGPT desktop app

```
[mcp_servers.searxng]
command = "npx"
args = ["-y", "mcp-searxng"]

[mcp_servers.searxng.env]
SEARXNG_URL = "http://localhost:8080"
```

Or run: `codex mcp add searxng --env SEARXNG_URL=http://localhost:8080 -- npx -y mcp-searxng`

#### Windsurf

Where: ~/.codeium/windsurf/mcp_config.json

```json
{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}
```

#### ChatGPT

Where: Not supported

ChatGPT on the web only connects to servers by URL. This one runs on your computer: the ChatGPT desktop app can start it from its MCP servers settings, with the same config as the Codex tab.

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

### How do I configure SearXNG?

| Setting | Kind | Required | What it does |
| --- | --- | --- | --- |
| `SEARXNG_URL` | env | yes | Base address of the SearXNG instance to search through. Separate several with semicolons for failover. Example: `https://search.example.com` |
| `SEARXNG_HTML_FALLBACK` | env | no | Set to true to scrape the HTML results page when the instance refuses JSON. Best effort only. Example: `true` |
| `MCP_HTTP_PORT` | env | no | Set it to serve over HTTP on that port. Leave it unset for the normal local setup. Example: `8080` |
| `MCP_HTTP_HOST` | env | no | Address the HTTP server binds to. |
| `MCP_HTTP_STATELESS` | env | no | Set to true to run HTTP without sessions, for load-balanced setups. |

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

### Good for

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

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

### What are the alternatives to SearXNG?

| Server | What it does | Tools | Runs on | Licence | Stars |
| --- | --- | --- | --- | --- | --- |
| [SearXNG](https://mcpshelf.co/servers/searxng) | Web search through your own SearXNG instance: no vendor, no API key. | 4 | Your computer | MIT | 1.3K |
| [Apify](https://mcpshelf.co/servers/apify) | Find and run ready-made Apify scrapers for maps, social media, shops and search. | 10 | Hosted or your computer | MIT | 13.6K |
| [BrowserTools MCP](https://mcpshelf.co/servers/browser-tools) | Console logs, network calls, screenshots and Lighthouse audits from your own Chrome tab. | 16 | Your computer | MIT | 7.3K |
| [ExecuteAutomation Playwright MCP](https://mcpshelf.co/servers/executeautomation-playwright) | A community Playwright server that also writes test code and emulates phones and tablets. | 33 | Your computer | MIT | 5.7K |
| [Wigolo](https://mcpshelf.co/servers/wigolo) | Search, fetch, crawl and extract the web locally, with no keys or metered bill. | 10 | Your computer | AGPL-3.0-only | 5.5K |
| [Perplexity MCP](https://mcpshelf.co/servers/perplexity) | Perplexity's search, answers and deep research, from Perplexity itself. | 4 | Hosted or your computer | MIT | 2.6K |

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

#### How do I add SearXNG to Cursor?

In ~/.cursor/mcp.json, or .cursor/mcp.json for one project, add an entry named searxng that runs npx -y mcp-searxng, with SEARXNG_URL set under env. Save, and the tools show up in Agent chat.

#### Can I use SearXNG in VS Code?

Yes, through GitHub Copilot. In .vscode/mcp.json, add a server named searxng with type stdio that runs npx -y mcp-searxng, with SEARXNG_URL set under env. Then switch Copilot Chat to Agent mode to use its tools.

#### Does SearXNG work with Codex?

Yes. Run codex mcp add searxng --env SEARXNG_URL=http://localhost:8080 -- npx -y mcp-searxng in a terminal, or add an [mcp_servers.searxng] table to ~/.codex/config.toml, which the Codex CLI and IDE extension share.

Full docs on GitHub: https://github.com/ihor-sokoliuk/mcp-searxng

## Notes for agents

Fetch these instead of parsing the HTML page:

- llms.txt: https://mcpshelf.co/llms.txt
- llms-full.txt: https://mcpshelf.co/llms-full.txt
- ai.txt: https://mcpshelf.co/ai.txt
- Full catalog (.md): https://mcpshelf.co/catalog.md
- API spec: https://mcpshelf.co/openapi.json
- MCP server: https://mcpshelf.co/mcp
- MCP manifest: https://mcpshelf.co/.well-known/mcp.json
- Developer docs: https://mcpshelf.co/developers

MCP endpoint (Streamable HTTP, no key): https://mcpshelf.co/mcp. REST API: https://mcpshelf.co/api/v1.

