SearXNG Server
README.md
<div align="center">
# 🔍 SearXNG MCP Server
**Privacy-respecting web search for AI assistants — use an operator-controlled or trusted SearXNG instance with Claude, Cursor, and more.**
[](https://github.com/ihor-sokoliuk/mcp-searxng/stargazers)
[](https://www.npmjs.com/package/mcp-searxng)
[](https://www.npmjs.com/package/mcp-searxng)
[](https://hub.docker.com/r/isokoliuk/mcp-searxng)
[](LICENSE)
[](https://scorecard.dev/viewer/?uri=github.com/ihor-sokoliuk/mcp-searxng)
[](https://www.bestpractices.dev/projects/13143)
[](https://glama.ai/mcp/servers/ihor-sokoliuk/mcp-searxng)
[](https://github.com/mcp/ihor-sokoliuk/mcp-searxng)
An [MCP server](https://modelcontextprotocol.io/introduction) that integrates the [SearXNG](https://docs.searxng.org) API, giving AI assistants web search capabilities.
✨ Featured in the [GitHub MCP Registry](https://github.com/mcp/ihor-sokoliuk/mcp-searxng).
</div>
## 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](#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:
```json
{
"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).
## 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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/tools.md) for capabilities and limits,
[configuration reference](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md) for settings, and
[historical deployment measurements](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/deployment-profiles.md) for
bounded resource-planning evidence.
## Why mcp-searxng?
<details>
<summary>Capability comparison recorded on 2026-07-29</summary>
As of 2026-07-29, the capability comparison below reflects the official
[Brave MCP](https://github.com/brave/brave-search-mcp-server),
[Exa MCP](https://github.com/exa-labs/exa-mcp-server), and
[Firecrawl MCP](https://github.com/mendableai/firecrawl-mcp-server) 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 | ✗ | ✗ | ✗ | ✓ |
</details>
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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md#core).
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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md#http-transport).
## 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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/tools.md) contains examples and the full parameter
reference. The optional [research workflow](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/research-workflow.md)
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.
<details>
<summary>NPM (global install)</summary>
```bash
npm install -g mcp-searxng
```
```json
{
"mcpServers": {
"searxng": {
"command": "mcp-searxng",
"env": {
"SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
}
}
}
}
```
</details>
<details>
<summary>Docker</summary>
**Pre-built image:**
```bash
docker pull isokoliuk/mcp-searxng:latest
```
Image signatures can be verified with Cosign — see [SECURITY.md](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/SECURITY.md) for instructions.
```json
{
"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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md#url-reader-controls) for the complete
behavior and Docker Compose example.
**Build locally:**
```bash
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`:
```yaml
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:
```json
{
"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`:
```yaml
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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/SECURITY.md#deployment-recommendations).
</details>
### HTTP Transport
Run HTTP independently, then connect the client. See the
[HTTP server guide](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/http-server.md) 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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md) 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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/http-server.md#choose-authentication).
Static bearer authentication and SearXNG Basic Auth protect different connections.
## Troubleshooting
| Symptom | Next check |
|---|---|
| Server absent or disconnected | [Client/process startup](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#client-and-process) |
| HTTP auth, session or proxy error | [HTTP connection](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#http-connection) |
| Tools appear but search fails | [SearXNG connection](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#search-and-searxng) |
| Empty, poor or stale results | [Filters, upstream metadata and cache](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#result-quality-and-cache) |
| URL/PDF failure or timeout | [URL reading](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/self-hosted-searxng.md#verify-searxng-directly)
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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/public-searxng-instances.md#json-rejection-and-html-fallback)
before enabling it on a service you do not control.
For a bug report, [collect a minimal reproduction and relevant errors](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#collect-useful-evidence).
## Documentation
[Configure search for useful coverage](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/search-configuration.md)
with tested upstream settings, specialist engine routes and MCP output controls.
The [deployment recipe](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/browser-solver-deployment.md)
includes a private Compose stack and optional browser providers, with dated
results and known failures.
[Find a guide by task](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/index.md). 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](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONTRIBUTING.md).
## License
MIT — see [LICENSE](LICENSE) for details.
TDQS
A4.2/5.0
Scored across 2 tools
Disambiguation5/5
The two tools have completely distinct purposes: searxng_web_search performs web searches, while web_url_read fetches and extracts content from URLs. There is no overlap or ambiguity between them.
Naming Consistency4/5
Both tools use snake_case and are descriptive, but the naming pattern differs: searxng_web_search includes the service prefix, while web_url_read does not. The verb-noun order is also inconsistent (verb-noun vs noun-verb). Overall, still clear and predictable.
Tool Count3/5
With only 2 tools, the set feels minimal but adequate for a basic web search and content retrieval use case. It does not overcomplicate, though it may leave room for additional utility tools.
Completeness4/5
The tools cover the core workflow: search the web and read full content of results. Minor gaps include advanced search filters (e.g., site, filetype) or management features, but the essential functionality is present.
Maintenance
ActivityActive
ResponsivenessUsually handled