SearXNG MCP Server
Connects AI assistants to a SearXNG instance's JSON search API, providing privacy-respecting web search with pagination, filters, direct answers, query suggestions and instance capability inspection, plus a tool to read a known URL as text or Markdown.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SearXNG MCP Server search the web for the latest MCP protocol updates"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Deep Re SearXNG
This fork combines the mcp-searxng v2.9.0 server with a local SearXNG/Valkey Compose stack, repo-scoped research skills, a read-only researcher agent and result validation. Node.js 22+ is required for local Node development. See NOTICE.md for source revisions.
Bundled stack and deep research
git clone https://github.com/FivePebblesGPT/deep-re-searxng.git
cd deep-re-searxng
docker compose -f compose.yaml up -d --build
curl --fail http://127.0.0.1:3000/healthFollow Deep research setup for the six skills, agent
configuration, Python validation and workflow. The default compose.yaml starts
SearXNG, Valkey and this fork's MCP HTTP service; docker-compose.yml is the
separate upstream MCP-only STDIO example and requires an existing SearXNG URL.
The server reference below is retained from upstream. Its NPX/Docker recipes install the upstream server distribution, not this fork's source-only research skills. Use the bundled-stack instructions above for the combined toolset.
Related MCP server: Google Search MCP Server
Upstream server reference
🔍 SearXNG MCP Server
Privacy-respecting web search for AI assistants — use an operator-controlled or trusted SearXNG instance with Claude, Cursor, and more.
An MCP server that integrates the SearXNG API, giving AI assistants web search capabilities.
✨ Featured in the GitHub MCP Registry.
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 or public-instance 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. |
You have an independently running HTTP service | Use your client's HTTP recipe with the full |
You need to operate an HTTP service | Follow the HTTP server guide. |
For clients using mcpServers JSON (such as Claude Desktop), add:
{
"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.
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.
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 for capabilities and limits, configuration reference for settings, and historical deployment measurements for bounded resource-planning evidence.
Why mcp-searxng?
As of 2026-07-29, the capability comparison below reflects the official Brave MCP, Exa MCP, and Firecrawl MCP 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 | âś— | âś— | âś— | âś“ |
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.
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.
Tools
Tool | Use it to |
| Find sources and refine results |
| Complete or refine a query |
| Inspect categories, engines and defaults |
| Read a known URL as text/Markdown |
The tool guide contains examples and the full parameter reference. The optional research workflow 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.
npm install -g mcp-searxng{
"mcpServers": {
"searxng": {
"command": "mcp-searxng",
"env": {
"SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
}
}
}
}Pre-built image:
docker pull isokoliuk/mcp-searxng:latestImage signatures can be verified with Cosign — see SECURITY.md for instructions.
{
"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 for the complete
behavior and Docker Compose example.
Build locally:
docker build -t mcp-searxng:latest -f Dockerfile .Use the same config above, replacing isokoliuk/mcp-searxng:latest with mcp-searxng:latest.
docker-compose.yml:
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.mdThe 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:
{
"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:
services:
mcp-searxng:
ports:
- "127.0.0.1:8080:8080"
environment:
- MCP_HTTP_PORT=8080
- MCP_HTTP_HOST=0.0.0.0Here 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.
HTTP Transport
Run HTTP independently, then connect the client. See the HTTP server guide 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 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. Static bearer authentication and SearXNG Basic Auth protect different connections.
Troubleshooting
Symptom | Next check |
Server absent or disconnected | |
HTTP auth, session or proxy error | |
Tools appear but search fails | |
Empty, poor or stale results | |
URL/PDF failure or timeout |
403 Forbidden from SearXNG
JSON output may be disabled, or an access-control layer may have denied the request. Follow the direct checks 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
before enabling it on a service you do not control.
For a bug report, collect a minimal reproduction and relevant errors.
Documentation
Configure search for useful coverage with tested upstream settings, specialist engine routes and MCP output controls. The deployment recipe includes a private Compose stack and optional browser providers, with dated results and known failures.
Find a guide by task. 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.
License
MIT — see LICENSE for details.
Available Tools
4 toolssearxng_instance_infoARead-only
Discovers capabilities from all reachable configured SearXNG instances via /config, including categories.common/available, engines.common/available, defaults, locales, and plugins.
Inputs: refresh, category, includeEngines, includeDisabled.
searxng_search_suggestionsARead-only
Returns autocomplete suggestions from the configured SearXNG instance. Use this to refine vague or partial queries before searching.
Inputs: query (required), language.
searxng_web_searchARead-only
Searches the web using SearXNG and returns a list of results, each with a title, URL, and content snippet. CRITICAL: The required parameter name is exactly query (not prompt, q, or any other name). Calls an external SearXNG instance; availability depends on the SEARXNG_URL configuration. Use pageno to paginate results; combine time_range and language to narrow scope. When engines and time_range are both provided, every selected engine must explicitly advertise time-range support via SearXNG /config; otherwise the request is rejected before search. To read the full text of a result URL, follow up with web_url_read.
Inputs: query (required), pages, pageno, engines, +8 more.
web_url_readARead-only
Fetches a URL and returns readable content as markdown. Content-type aware: HTML is converted to markdown; JSON is pretty-printed; plain text, YAML, TOML, and XML are returned as fenced readable text. PDF text extraction is supported with bounded input, output, page count, time, concurrency, and memory; OCR is not supported. Binary, media, archive, and octet-stream downloads other than PDFs are intentionally rejected instead of being returned as raw bytes. When the operator configures browser solvers, mcp-searxng attempts FlareSolverr first and then Byparr only after a busy or transient-unavailable acquisition; cache hits bypass acquisition and a final busy or unavailable provider uses one uncached direct-fetch fallback. Three modes: (1) Full content — omit filtering params; use startChar/maxLength to paginate large pages. (2) Section extraction — set section to return content under a specific heading. (3) Headings only — set readHeadings: true to list all headings (mutually exclusive with other filtering params). Returns an error string if the URL is unreachable or content cannot be extracted. Use after searxng_web_search to read the full content of individual result URLs.
Inputs: url (required), section, maxLength, startChar, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: web search, autocomplete suggestions, instance capability discovery, and URL content reading. The descriptions explicitly guide follow-up workflows, making misselection unlikely.
Three tools share the predictable `searxng_` prefix and snake_case, but `web_url_read` breaks that prefix pattern. The naming is still readable and mostly consistent.
Four tools is well-scoped for a SearXNG integration: search, suggestions, instance info, and content fetching. Each earns its place without redundancy.
The surface covers the main search workflow end-to-end, including query refinement and reading result content. Some advanced search modes may be handled via parameters rather than dedicated tools, leaving only minor gaps.
Maintenance
Related MCP Connectors
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Web search, data extraction and controlled browser automation for AI assistants via OAuth.
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Enable AI assistants to perform web searches using Perplexity's Sonar Pro.
Related MCP Servers
- FlicenseCqualityDmaintenanceEnables web search capabilities through the Tavily API via the Model Context Protocol. Allows users to perform web searches and retrieve information from the internet through natural language queries.5-
- AlicenseAqualityDmaintenanceEnables users to perform Google Custom Search queries through the Model Context Protocol. Requires Google API credentials and Custom Search Engine configuration for web search functionality.1MIT
- AlicenseAqualityDmaintenanceProvides a bridge between AI assistants and SearXNG, a privacy-respecting metasearch engine, enabling web searches and engine discovery via the Model Context Protocol.230 npm2Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI applications to perform web searches using a YaCy search engine instance through the Model Context Protocol.1MIT