searxng-mcp
SearXNG search MCP for Claude Code and Grok — privacy-respecting web search and page extraction for AI agents and any MCP client.
searxng-mcp is a token-efficient Model Context Protocol (MCP) server that connects your self-hosted SearXNG 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):
/plugin marketplace add 88plug/claude-code-plugins
/plugin install searxng@88plug
Grok Build
grok plugin marketplace add 88plug/claude-code-plugins
grok plugin install searxng@88plug --trust
Standalone MCP server — any client, no install step:
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 withSEARXNG_MCP_BASE_URL.
Quickstart
Point the server at a local SearXNG backend and confirm it is healthy:
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
MCP tools
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 supportsearxng://guide— available tools and when to use eachquick_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:
SEARXNG_MCP_TRANSPORT=stdio uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp
Streamable HTTP for a private service or team deployment:
uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp \
--transport streamable-http --host 0.0.0.0 --port 8811
Docker
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:
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_urlandfetch_manycan request client-supplied URLs, so putstreamable-httpbehind auth or a reverse proxy. Apply the same controls you would for any SSRF-capable tool.SEARXNG_MCP_FETCH_VERIFY_TLS=0is only for private or self-signed backends.
Configuration
Common environment variables:
SEARXNG_MCP_BASE_URL— SearXNG base URL. Defaulthttp://127.0.0.1:8890SEARXNG_MCP_FALLBACK_BASE_URLS— comma-separated fallback SearXNG instancesSEARXNG_MCP_TRANSPORT—stdio,streamable-http, orsseSEARXNG_MCP_SEARCH_TIMEOUT— backend search timeout, secondsSEARXNG_MCP_FETCH_TIMEOUT— fetch timeout, secondsSEARXNG_MCP_SEARCH_CACHE_TTL— search cache TTL, secondsSEARXNG_MCP_FETCH_CACHE_TTL— fetch cache TTL, secondsSEARXNG_MCP_FETCH_VERIFY_TLS— set to0to skip TLS verification on fetchesSEARXNG_MCP_CACHE_DIR— cache directory path
SEARXNG_MCP_RENDER_TIMEOUT— browser navigation timeout for rendered fetchesSEARXNG_MCP_RENDER_WAIT_MS— extra wait after DOM content loadSEARXNG_MCP_RENDER_CONCURRENCY— concurrent rendered fetch limitSEARXNG_MCP_RENDER_HEADLESS— set to0to show the browserSEARXNG_MCP_RENDER_BROWSER_PATH— explicit Chromium or Chrome binary pathSEARXNG_MCP_RENDER_SANDBOX— set to1to keep Chromium sandboxing enabledSEARXNG_MCP_RENDER_BLOCK_RESOURCES— set to0to allow images, fonts, stylesheets, and mediaSEARXNG_MCP_RENDER_AUTO_FALLBACK— set to0to disable automatic rendered fallbackSEARXNG_MCP_RENDER_AUTO_MIN_WORDS— lower to make auto-render more aggressiveSEARXNG_MCP_RENDER_AUTO_MIN_CHARS— lower to make auto-render more aggressive
Client configs
Use either command shape with any MCP client:
searxng-mcp— when the entry point is onPATH(afteruv syncfrom a checkout, orpipx 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):
{
"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 for Codex CLI, gemini-cli, and more.
Benchmarks
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
- Getting started
- Installation
- Configuration
- Deployment
- Security
- Tool reference
- Client configs
- Comparison
- Changelog
- SearXNG docs
Development
From a checkout:
uv sync
uv run searxng-mcp
Build and test:
uv sync --all-groups
uv run pytest -q
uv run python -m compileall src
uv run mkdocs build --strict
Contributions welcome. See CONTRIBUTING.md and the code of conduct.
License
Released under the Functional Source License, Version 1.1, ALv2 Future 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: [email protected].