# searxng-mcp-server
Self-hosted [SearXNG](https://github.com/searxng/searxng) metasearch for MCP clients — thirteen tools (web, image, news, video, music and paper search, search+fetch in one call, page fetch, site crawling, query suggestions, instance info, instance doctor and a deep-search dossier) with no API keys and no tracking. Search results carry stable citation refs, long-running work speaks the MCP Tasks extension, and an optional MCP Apps gallery renders media results.
[](https://insiders.vscode.dev/redirect/mcp/install?name=searxng&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22searxng-mcp-server%22%5D%7D)
[](https://cursor.com/en/install-mcp?name=searxng&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22searxng-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/searxng-mcp-server)
[](./LICENSE)
[](https://github.com/bumbaRasch/searxng-mcp-server/actions/workflows/ci.yml)
[Documentation](docs/design.md) · [Changelog](CHANGELOG.md) · [npm](https://www.npmjs.com/package/searxng-mcp-server) · [SearXNG](https://github.com/searxng/searxng) · [Report an issue](https://github.com/bumbaRasch/searxng-mcp-server/issues)
## Why
Search-API servers mean signups, API keys, rate limits, and provider-side tracking of every query. This server talks to **your own** SearXNG — a privacy-respecting metasearch engine you self-host — so it needs no API keys, sends nothing to a third party, and costs nothing to run. Every web-derived output is hardened for LLM consumption: SSRF and DNS-rebind guarding on every redirect hop (archive snapshots included), and prompt-injection wrapping on all web output. Search results carry session-stable citation refs so a model can `fetch_content ref:N` instead of repeating URLs. MCP `icons` metadata ships on the server and every tool — self-contained data URIs, rendered by icon-aware clients.
## A typical session
```text
# Arguments are JSON in real MCP calls; this shows the flow:
autocomplete "rust asy" → suggestions to refine the query
search "rust async" (rerank: true) → ranked results, each with a stable ref:N
fetch_content ref:3 → result 3 as clean Markdown, by citation ref
search_and_fetch "tokio vs async-std" → search + top pages' full content in one call
doctor → is the instance itself the problem?
deep_search "which runtime for my webhook" → iterative cited dossier (tasks-aware)
```
## Architecture
MCP client → stdio (default) or Streamable HTTP (opt-in) → this server → your SearXNG (Docker) → upstream engines. Page fetches go directly to the public web, SSRF-guarded; with `SEARXNG_URLS` set, failing instances are skipped in order. Diagram and module map: [docs/design.md](docs/design.md).
## Quick start
Requires Node >= 22.19 (the `npx` runtime) and Docker for the SearXNG stack.
### 1. Run SearXNG
```bash
printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)" > .env
docker compose up -d
curl -fsS 'http://localhost:8888/search?q=test&format=json' | head -c 80
```
The bundled `docker-compose.yml` enables the JSON API and binds `127.0.0.1` only — the API is unauthenticated, so never expose the port publicly. Engine credentials (e.g. an OpenAlex `api_key`) belong in `searxng/settings.yml`.
### 2. Add to any MCP client
Works in Claude Desktop, Cursor and most `mcpServers`-style clients:
```json
{
"mcpServers": {
"searxng": {
"command": "npx",
"args": ["-y", "searxng-mcp-server"]
}
}
}
```
`SEARXNG_URL` already defaults to `http://localhost:8888`; add an `env` block only to override. Cursor reads the same shape from `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project).
OpenCode
Global config `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"searxng": {
"type": "local",
"command": ["npx", "-y", "searxng-mcp-server"],
"enabled": true
}
}
}
```
Claude Code
One command, available in all projects:
```bash
claude mcp add --scope user searxng -- npx -y searxng-mcp-server
```
ZCode
User scope in `~/.zcode/cli/config.json` (`command` is a string, key is `mcp.servers`):
```json
{
"mcp": {
"servers": {
"searxng": {
"type": "stdio",
"command": "npx",
"args": ["-y", "searxng-mcp-server"]
}
}
}
}
```
From source
```bash
git clone https://github.com/bumbaRasch/searxng-mcp-server && cd searxng-mcp-server
pnpm install && pnpm build
```
Then use `node /absolute/path/to/searxng-mcp-server/dist/index.js` as the command in any config above.
Parameters
- **search** — `query` (string, required unless `queries` is given): max 500 chars. `queries` (string[2–5]): batch mode, one result set per query in input order. Optional: `categories` (string[]), `engines` (string[]), `language`, `time_range` (`day` | `week` | `month` | `year`), `pageno`, `safesearch` (0/1/2), `max_results` (1–50, default 10; per query in batch mode), `min_score` (number ≥ 0, drops scored results below it), `rerank` (boolean: heuristic reorder by query/title overlap, freshness and configured domain boosts), `detail` (`full` default | `compact` markdown rendering). Results carry a session-stable `ref`.
- **image_search** / **news_search** / **video_search** / **music_search** / **paper_search** — `query` (required) plus the shared optional args: `engines`, `language`, `pageno`, `safesearch`, `max_results`, `detail`, and `time_range` (all five support the freshness filter).
- **fetch_content** — `url` (string, required): absolute http/https, or `ref:N` to cite a search result, max 2048 chars. `max_chars` (1000–200000, default `MAX_CHARS` 25000). `offset` (int ≥ 0): window start into the extracted content — continue from the returned `nextOffset`. `outline: true` adds `headings` (`{text, offset, level}`: markdown `#`-lines, `[Page N]` markers for PDFs) with offsets into the scanned content. `section` returns one heading region only — case-insensitive exact heading match, through the next same-or-higher-level heading — with `offset`/`max_chars` applying inside it. `timeout_ms` (max 120000). `archive: true` retries a dead link (404/410/5xx, unreachable, timed out) through the closest Internet Archive snapshot (result marked `archived`). Text PDFs are extracted per page (`[Page N]` sections, `pages` count in the output).
- **search_and_fetch** — `query` (required) plus the search args and: `fetch_top` (1–5, default 3) fetches the top delivered results' full content; `max_chars` caps each page. Output: the search envelope plus `pages[]` (one entry per fetched page with `content` or `error`).
- **crawl_site** — `url` (seed, required), `max_pages` (1–30, default 10). Follows same-origin links breadth-first (robots.txt honored best-effort) and returns a manifest with a `ref` per page; the extracted content is cached, so `fetch_content ref:N` reads it without re-fetching.
- **doctor** — no arguments. Returns `checks[]` (`id`, `ok`, `detail`) covering the JSON API, `/config`, unresponsive engines and limiter state, plus a `healthy` verdict.
- **deep_search** — `query` (required), `max_iterations` (1–4, default 2), `sources_per_iteration` (1–5, default 2), `max_results`. Returns a cited dossier (`sources[]` with refs, `notes[]` excerpts, optional `synthesis`). With `io.modelcontextprotocol/tasks` negotiated, returns a task handle to poll via `tasks/get`.
- **autocomplete** — `query` (string, required): the prefix to complete, max 200 chars. Suggestions follow the instance's configured language.