Content
<div align="center">
# searxng-mcp
SearXNG search MCP for Claude Code and Grok — privacy-respecting web search and page extraction for AI agents and any MCP client.
[](https://github.com/88plug/searxng-mcp/actions/workflows/plugin-validate.yml)
[](LICENSE)
[](https://88plug.github.io/searxng-mcp/)
[](https://github.com/88plug/claude-code-plugins)
[](https://deepwiki.com/88plug/searxng-mcp)
</div>
`searxng-mcp` is a token-efficient [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that connects your self-hosted [SearXNG](https://docs.searxng.org/) metasearch instance to Claude Code, Anthropic-compatible clients, and other LLM / AI-agent tooling. You get privacy-respecting web search across 70+ engines plus readable page extraction — without shipping raw HTML into the model context.
Search, multi-query research, and fetch tools keep model-visible output short. Full result payloads stay in hidden `_meta`, so tokens go to answers. Deploy via stdio for local Claude workflows, or streamable-http / Docker for a self-hosted MCP service with optional Playwright rendered fetch for JS-heavy pages.
## Install
Claude Code plugin (hub-first):
```text
/plugin marketplace add 88plug/claude-code-plugins
/plugin install searxng@88plug
```
### Grok Build
```text
grok plugin marketplace add 88plug/claude-code-plugins
grok plugin install searxng@88plug --trust
```
Standalone MCP server — any client, no install step:
```bash
uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp
```
> [!NOTE]
> You need a reachable SearXNG instance. Default base URL is `http://127.0.0.1:8890`. Override with `SEARXNG_MCP_BASE_URL`.
## Quickstart
Point the server at a local SearXNG backend and confirm it is healthy:
```bash
export SEARXNG_MCP_BASE_URL=http://127.0.0.1:8890
uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp
```
In your MCP client, call `health`. A healthy backend returns `ok: true` with backend, cache, and render details. Then call `search` — you get a compact ranked list; the full payload stays in `_meta`.
Rendered fetch ships in the default install. If the host has Chromium or Chrome, the server uses it. Otherwise the first rendered fetch bootstraps Playwright Chromium into the user cache.
## Features
| Feature | Detail |
| --- | --- |
| Token-efficient MCP tools | Compact model-visible output; full payloads in hidden `_meta` |
| Parallel research | Multi-query search and fetch fan-out with dedupe and merged ranking |
| Rendered extraction | Playwright/Chromium path for JS-heavy pages; no extra install flags |
| Self-hosted deployment | stdio, streamable-http, SSE, Docker, and Compose for private MCP services |
| Thin by design | SearXNG does the search; this server shapes tools, cache, extract, transport |
## MCP tools
| Tool | What it does |
| --- | --- |
| `search` | Concise web search; full raw payload in `_meta` |
| `search_many` | Parallel fan-out across queries, with dedupe and merged ranking |
| `search_and_fetch` | Search plus source extraction in one call |
| `research` | Multi-query search with batch fetches and merged, cited sources |
| `fetch_url` | Readable page extraction with citations |
| `fetch_many` | Parallel URL extraction with caching |
| `health` | Backend, cache, and render status |
Tools surface as `mcp__searxng__search`, `mcp__searxng__fetch_url`, and so on.
Resources and optional prompts:
- `searxng://config` — current settings, transport mode, and render support
- `searxng://guide` — available tools and when to use each
- `quick_lookup`, `deep_research`, `research_workflow` — optional prompts for clients that support prompt surfaces
## Transports and deployment
Supports `stdio`, `streamable-http`, and `sse`.
Local stdio for desktop clients and private workflows:
```bash
SEARXNG_MCP_TRANSPORT=stdio uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp
```
Streamable HTTP for a private service or team deployment:
```bash
uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp \
--transport streamable-http --host 0.0.0.0 --port 8811
```
### Docker
```bash
docker build -t searxng-mcp .
docker run --rm -p 8811:8811 --add-host=host.docker.internal:host-gateway \
-e SEARXNG_MCP_BASE_URL=http://host.docker.internal:8890 \
searxng-mcp
```
Hardened image and Compose for a longer-running self-hosted service:
```bash
docker build -f Dockerfile.prod -t searxng-mcp:prod .
cp docker-compose.env.example .env
docker compose up --build -d
```
> [!TIP]
> If you expose the HTTP transport, treat it like an internal service. `fetch_url` and `fetch_many` can request client-supplied URLs, so put `streamable-http` behind auth or a reverse proxy. Apply the same controls you would for any SSRF-capable tool. `SEARXNG_MCP_FETCH_VERIFY_TLS=0` is only for private or self-signed backends.
## Configuration
Common environment variables:
- `SEARXNG_MCP_BASE_URL` — SearXNG base URL. Default `http://127.0.0.1:8890`
- `SEARXNG_MCP_FALLBACK_BASE_URLS` — comma-separated fallback SearXNG instances
- `SEARXNG_MCP_TRANSPORT` — `stdio`, `streamable-http`, or `sse`
- `SEARXNG_MCP_SEARCH_TIMEOUT` — backend search timeout, seconds
- `SEARXNG_MCP_FETCH_TIMEOUT` — fetch timeout, seconds
- `SEARXNG_MCP_SEARCH_CACHE_TTL` — search cache TTL, seconds
- `SEARXNG_MCP_FETCH_CACHE_TTL` — fetch cache TTL, seconds
- `SEARXNG_MCP_FETCH_VERIFY_TLS` — set to `0` to skip TLS verification on fetches
- `SEARXNG_MCP_CACHE_DIR` — cache directory path
<details>
<summary>Rendered fetch (Playwright) variables</summary>
- `SEARXNG_MCP_RENDER_TIMEOUT` — browser navigation timeout for rendered fetches
- `SEARXNG_MCP_RENDER_WAIT_MS` — extra wait after DOM content load
- `SEARXNG_MCP_RENDER_CONCURRENCY` — concurrent rendered fetch limit
- `SEARXNG_MCP_RENDER_HEADLESS` — set to `0` to show the browser
- `SEARXNG_MCP_RENDER_BROWSER_PATH` — explicit Chromium or Chrome binary path
- `SEARXNG_MCP_RENDER_SANDBOX` — set to `1` to keep Chromium sandboxing enabled
- `SEARXNG_MCP_RENDER_BLOCK_RESOURCES` — set to `0` to allow images, fonts, stylesheets, and media
- `SEARXNG_MCP_RENDER_AUTO_FALLBACK` — set to `0` to disable automatic rendered fallback
- `SEARXNG_MCP_RENDER_AUTO_MIN_WORDS` — lower to make auto-render more aggressive
- `SEARXNG_MCP_RENDER_AUTO_MIN_CHARS` — lower to make auto-render more aggressive
</details>
## Client configs
Use either command shape with any MCP client:
- `searxng-mcp` — when the entry point is on `PATH` (after `uv sync` from a checkout, or `pipx install`)
- `uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp` — runs from this repo with no install step
Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"searxng": {
"command": "uvx",
"args": ["--from", "git+https://github.com/88plug/searxng-mcp", "searxng-mcp"],
"env": {
"SEARXNG_MCP_BASE_URL": "http://127.0.0.1:8890",
"SEARXNG_MCP_TRANSPORT": "stdio"
}
}
}
}
```
See [client configs](docs/reference/client-configs.md) for Codex CLI, gemini-cli, and more.
## Benchmarks
```bash
uv run searxng-mcp-bench --rounds 3
```
Reports raw backend latency, token-visible output size, merged multi-query search latency, research latency, fetch extraction latency, rendered fetch latency, and batch variants.
## Documentation
Full site: **[88plug.github.io/searxng-mcp](https://88plug.github.io/searxng-mcp/)**
- [Getting started](docs/getting-started.md)
- [Installation](docs/installation.md)
- [Configuration](docs/configuration.md)
- [Deployment](docs/deployment.md)
- [Security](docs/security.md)
- [Tool reference](docs/reference/tools.md)
- [Client configs](docs/reference/client-configs.md)
- [Comparison](docs/comparison.md)
- [Changelog](CHANGELOG.md)
- [SearXNG docs](https://docs.searxng.org/)
## Development
From a checkout:
```bash
uv sync
uv run searxng-mcp
```
Build and test:
```bash
uv sync --all-groups
uv run pytest -q
uv run python -m compileall src
uv run mkdocs build --strict
```
Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md).
## License
Released under the [Functional Source License, Version 1.1, ALv2 Future License](LICENSE) (`FSL-1.1-ALv2`).
Free to use, copy, modify, and redistribute for any purpose except a Competing Use — offering this software (or a substantially similar substitute) as a commercial product or service. Each released version converts to the Apache License 2.0 on the second anniversary of its release date.
For commercial-use inquiries outside the Permitted Purpose: andrew@88plug.com.
