
SearXNG MCP Server
Web search through your own SearXNG instance: no vendor, no API key.
- 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).
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.
| Tool | What it is for |
|---|---|
searxng_instance_info | Asks your SearXNG instance which engines, categories and defaults it offers. |
searxng_search_suggestions | Fetches autocomplete ideas to sharpen a vague query before searching. |
searxng_web_search | Runs a search through your SearXNG instance and returns titles, links and snippets, with paging and filters. |
web_url_read | Opens 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 mcp add --scope user --env SEARXNG_URL=http://localhost:8080 --transport stdio searxng -- npx -y mcp-searxngSwap in your instance's address. Check it with claude mcp get searxng, then /mcp inside Claude Code.
Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
"mcpServers": {
"searxng": {
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "http://localhost:8080"
}
}
}
}Where it goes: claude_desktop_config.json (Settings → Developer → Edit Config)
{
"mcpServers": {
"searxng": {
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "http://localhost:8080"
}
}
}
}Where it goes: .vscode/mcp.json in your project
{
"servers": {
"searxng": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "http://localhost:8080"
}
}
}
}Where it goes: ~/.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
Where it goes: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"searxng": {
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "http://localhost:8080"
}
}
}
}Where it goes: 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: 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.
| Setting | What it does |
|---|---|
SEARXNG_URLEnvironment variable · required | Base address of the SearXNG instance to search through. Separate several with semicolons for failover.https://search.example.com |
SEARXNG_HTML_FALLBACKEnvironment variable | Set to true to scrape the HTML results page when the instance refuses JSON. Best effort only.true |
MCP_HTTP_PORTEnvironment variable | Set it to serve over HTTP on that port. Leave it unset for the normal local setup.8080 |
MCP_HTTP_HOSTEnvironment variable | Address the HTTP server binds to. |
MCP_HTTP_STATELESSEnvironment variable | Set 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

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

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

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