SearXNG HTTP MCP
About
Self-contained SearXNG MCP server in Docker with 200+ search engines, dual transport (HTTP + stdio), API key auth, and built-in Web UI.
Details
- Author
- whw23
- Categories
- Search, Other, API
Jump to
Setup
Install SearXNG HTTP MCP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/whw23/searxng_http_mcp
Follow the installation instructions in the repository README, then restart your MCP client.
中文·Quick Start·Features·Architecture·Comparison·Usage·MCP Tools·Client Config·Plugin·Contributing
A self-contained MCP server that wrapsSearXNG— a free, privacy-respecting metasearch engine that aggregates results from 200+ search engines.
Server mode— deploy once, connect from any client:
docker run -d --name searxng-mcp --restart unless-stopped \ -p YOUR_PORT:8888 --memory=512m --cpus=1 \ ghcr.io/whw23/searxng-http-mcp:latest
Thenconnect your clienttohttp://YOUR_HOST:YOUR_PORT/mcp/. To enable API key auth, seeAuthentication.
Local mode— no server needed, run directly in your client:
docker run --rm -i --memory=512m --cpus=1 ghcr.io/whw23/searxng-http-mcp:latest --stdio
Add this as a stdio MCP server in your client — seeClient Configurationfor details.
uvx mode— if you already have SearXNG running (install guide):
SetSEARXNG_URLto point to your SearXNG instance (default:http://127.0.0.1:8080).
- 🔍 200+ search engines — Google, Bing, DuckDuckGo, Brave, and more via SearXNG
- 📂 30+ categories — news, images, videos, science, IT, and more
- 📄 Multi-page fanout — up to 5 pages per call
- 💡 Autocomplete suggestions — discover relevant search terms
- 🗂 Engine discovery — query available engines grouped by category
- 🎯 Token-efficient — results trimmed to essentials
- 📦 Self-contained — SearXNG built into Docker image
- 🔄 Triple transport — HTTP server, Docker stdio, and uvx standalone
- 🔐 Authentication —x-api-key+ HTTP Basic Auth
- 🌐 Reverse proxy — SearXNG Web UI on the same port
- ⚡ Dynamic tool descriptions — live category lists injected at startup
- 📐 Rich JSON Schema — enum constraints, range limits, and descriptions on every parameter
graph LR Client(["client:YOUR_PORT"]) --> Expose(":8888") subgraph Container["🐳 Docker Container"] direction LR Expose --> Auth{Auth} Auth -->|/mcp| MCP[FastMCP Server] Auth -->|/*| Proxy[Reverse Proxy] MCP --> SearXNG[SearXNG :8080] Proxy --> SearXNG end style Expose fill:none,stroke:#2496ed,stroke-dasharray:5 5,color:#2496ed style Client fill:#4a90d9,color:#fff,stroke:#3a7bc8 style Container fill:#f0f4f8,stroke:#2496ed,stroke-width:2px,color:#2496ed style Auth fill:#f5a623,color:#fff,stroke:#d4900e style MCP fill:#50c878,color:#fff,stroke:#3da85e style Proxy fill:#9b59b6,color:#fff,stroke:#8344a5 style SearXNG fill:#e74c3c,color:#fff,stroke:#c0392b
- 88plug/searxng-mcp— richest tool surface among SearXNG MCPs (7 tools: rendered fetch, research mode, parallel queries)
- ihor/mcp-searxng— most GitHub stars among SearXNG MCPs
- open-webSearch— top free multi-engine alternative outside the SearXNG ecosystem (Bing, Baidu, DuckDuckGo, Brave, etc.)
- exa-mcp-server— most popular commercial search API MCP
- Perplexity MCP— commercial AI-powered search, highest star count in the search MCP space
MCP is designed for composition — clients connect multiple specialized servers, each doing one thing well. Some alternatives bundle URL fetching, rendered page extraction, multi-query fan-out, or research modes into the search server. We keep the tool surface to three (search, autocomplete, engine discovery) by design:
- URL fetching is a separate concern.MCP clients already ship dedicated tools (WebFetch, Playwright MCP, Jina Reader). Bundling fetch into a search server mixes responsibilities and duplicates the client ecosystem.
- Multi-query parallel search is client-side orchestration.LLM clients can fire multiplesearchcalls in parallel — asearch_manytool only adds token overhead for tool selection with no real benefit.
- Research / synthesis belongs in the LLM layer.The model is the best synthesizer. Pushing multi-step research logic into the MCP server couples application concerns to infrastructure.
Instead we invest in what the alternatives above lack:complete SearXNG API coverage(categories, autocomplete, engine metadata — capabilities most wrappers leave on the table),self-contained deployment, authentication, Web UI reverse proxy, and AI coding agent plugin integration (Claude Code / Copilot CLI / Codex CLI).
# Without authentication docker run -d --name searxng-mcp --restart unless-stopped \ -p YOUR_PORT:8888 --memory=512m --cpus=1 \ ghcr.io/whw23/searxng-http-mcp:latest # With authentication docker run -d --name searxng-mcp --restart unless-stopped \ -p YOUR_PORT:8888 --memory=512m --cpus=1 \ -e API_KEY=your-secret-key \ ghcr.io/whw23/searxng-http-mcp:latest
docker run --rm -i --memory=512m --cpus=1 \ ghcr.io/whw23/searxng-http-mcp:latest --stdio
No ports exposed. Communication via stdin/stdout. SearXNG runs internally for the MCP tools.
# Connect to a local SearXNG instance (default: http://127.0.0.1:8080) uvx searxng-http-mcp # Connect to a remote SearXNG instance SEARXNG_URL=http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT uvx searxng-http-mcp
Requires Python 3.14+ and an existing SearXNG instance. No Docker needed.
WhenAPI_KEYis set, all requests require one of:
- x-api-keyheader— for MCP clients:x-api-key: your-key
- HTTP Basic Auth— for browsers
[!TIP]Browser Login:When accessing the Web UI withAPI_KEYenabled, the browser will show a login dialog.Leave the username emptyand enter your API key as thepassword.
WhenAPI_KEYis not set, all requests are open.
Aggregates results from 200+ search engines with privacy.
Returns:results, answers, suggestions, corrections, infoboxes.
No parameters. Returns the list of enabled engines grouped by category.
{ "categories": ["general", "images", "videos", "news", ...], "engines": ["google", "bing", "duckduckgo", ...], "category_engines": { "general": ["google", "bing", "duckduckgo", "brave", ...], "science": ["arxiv", "google scholar", "pubmed", ...], ... } }
Use this to discover what engines are available before callingsearchwith specificenginesorcategoriesfilters.
The following is abaselineserver-mode (remote HTTP) example using the standardmcpServersJSON structure. Many clients accept this structure, but field names and requiredtypevalues differ — see the NOTE below and adjust for your client:
{ "mcpServers": { "searxng": { "type": "http", "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } }
[!NOTE] Field-name differences:ZCodeusesmcp.servers;Kilo Codeuses a top-levelmcpkey with"type": "remote";WindsurfusesserverUrlinstead ofurl;VS Code Copilotuses a top-levelserverskey;OpenCodenests undermcpwith"type": "remote";CodexandHermesusemcp_servers(TOML/YAML). ForClaude Code,"type": "http"isrequired— without it the entry is read as a stdio server and skipped. ForCline, set"type": "streamableHttp"on remote HTTP servers.
Server mode— edit~/Library/Application Support/Claude/claude_desktop_config.json:
{ "mcpServers": { "searxng": { "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } }
{ "mcpServers": { "searxng": { "command": "docker", "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"] } } }
{ "mcpServers": { "searxng": { "command": "uvx", "args": ["searxng-http-mcp"], "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" } } } }
claude mcp add --transport http searxng http://YOUR_HOST:YOUR_PORT/mcp/ \ --header "x-api-key: your-secret-key"
Server mode (JSON)— the samemcpServersstructure works in ateam-sharedproject.mcp.jsonor auser-wideglobal~/.claude.json:
{ "mcpServers": { "searxng": { "type": "http", "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } }
claude mcp add --transport stdio searxng -- docker run --rm -i --memory=512m --cpus=1 ghcr.io/whw23/searxng-http-mcp:latest --stdio
claude mcp add --transport stdio searxng -- uvx searxng-http-mcp
Server mode— add to~/.codex/config.toml:
[mcp_servers.searxng] url = "http://YOUR_HOST:YOUR_PORT/mcp/" http_headers = { "x-api-key" = "your-secret-key" }
[mcp_servers.searxng] command = "docker" args = ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]
[mcp_servers.searxng] command = "uvx" args = ["searxng-http-mcp"]
{ "mcpServers": { "searxng": { "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } }
{ "mcpServers": { "searxng": { "command": "docker", "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"] } } }
{ "mcpServers": { "searxng": { "command": "uvx", "args": ["searxng-http-mcp"], "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" } } } }
{ "servers": { "searxng": { "type": "http", "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } }
{ "servers": { "searxng": { "type": "stdio", "command": "docker", "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"] } } }
{ "servers": { "searxng": { "type": "stdio", "command": "uvx", "args": ["searxng-http-mcp"], "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" } } } }
Server mode— add to~/.codeium/windsurf/mcp_config.json:
{ "mcpServers": { "searxng": { "serverUrl": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } }
{ "mcpServers": { "searxng": { "command": "docker", "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"] } } }
{ "mcpServers": { "searxng": { "command": "uvx", "args": ["searxng-http-mcp"], "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" } } } }
Configure via Cline's MCP settings panel in VS Code (Cline > MCP Servers > Add).
{ "mcpServers": { "searxng": { "type": "streamableHttp", "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } }
{ "mcpServers": { "searxng": { "command": "docker", "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"] } } }
{ "mcpServers": { "searxng": { "command": "uvx", "args": ["searxng-http-mcp"], "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" } } } }
{ "mcp": { "searxng": { "type": "remote", "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } }
{ "mcp": { "searxng": { "type": "local", "command": ["docker", "run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"] } } }
{ "mcp": { "searxng": { "type": "local", "command": ["uvx", "searxng-http-mcp"] } } }
Server mode— edit~/.hermes/config.yaml:
mcp_servers: searxng: url: "http://YOUR_HOST:YOUR_PORT/mcp/" headers: x-api-key: "your-secret-key"
mcp_servers: searxng: command: "docker" args: ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]
mcp_servers: searxng: command: "uvx" args: ["searxng-http-mcp"]
Server mode— edit~/.zcode/cli/config.json(user-wide) or.zcode/config.json(project):
{ "mcp": { "servers": { "searxng": { "type": "http", "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" } } } } }
{ "mcp": { "servers": { "searxng": { "command": "docker", "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"] } } } }
{ "mcp": { "servers": { "searxng": { "command": "uvx", "args": ["searxng-http-mcp"], "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" } } } } }
ZCode also accepts the standardmcpServersstructure (e.g. in.agents/mcp.json). Alternatively, add servers viaSettings → MCP Servers → New MCP Server.
Server mode— edit~/.config/kilo/kilo.jsonc(global) or.kilo/kilo.jsonc(project):
{ "mcp": { "searxng": { "type": "remote", "url": "http://YOUR_HOST:YOUR_PORT/mcp/", "headers": { "x-api-key": "your-secret-key" }, "enabled": true } } }
{ "mcp": { "searxng": { "type": "local", "command": ["docker", "run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"], "enabled": true } } }
{ "mcp": { "searxng": { "type": "local", "command": ["uvx", "searxng-http-mcp"], "environment": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" }, "enabled": true } } }
Install the MCP adapter once, then add a standardmcpServersblock — e.g. in~/.pi/agent/mcp.json(all projects) or.pi/mcp.json(project):
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
