SearXNG
About
Integrates SearXNG API to enable web searches with pagination control for up-to-date information retrieval and content analysis.
Details
- Author
- ihor-sokoliuk
- Repository
- ihor-sokoliuk/mcp-searxng
- GitHub stars
- 247
- Downloads
- 2,151
- License
- MIT License
- Categories
- Search, Community, Other, AI, Design, Developer Tools, Frontend, Infrastructure, API
- Tags
- #web
Jump to
- Web Search: General, news, and article queries with pagination, time-range/language/safe-search filters, relevance filtering (min_score), and formatted-text or raw-JSON output selected per call (response_format) or with the operator default (SEARXNG_DEFAULT_RESPONSE_FORMAT).
- Instance Failover & Fan-out: Configure interchangeable SearXNG replicas in SEARXNG_URL; searches fail over in order by default, or query all healthy replicas in parallel and merge results with SEARXNG_FANOUT.
- Direct Answers & Metadata: Text results surface SearXNG answers, corrections, suggestions, and infoboxes before the result list.
- Search Suggestions: Query autocomplete via SearXNG's /autocompleter endpoint.
- Instance Capability Discovery: Inspect configured categories, engines, defaults, locales, and plugins from /config.
- URL Content Reading: Content-type-aware Markdown conversion, including bounded PDF text extraction, with pagination, section filtering, paragraph ranges, and heading extraction.
- Browser Solver Support: For each uncached URL that passes static URL validation and the HEAD size preflight, optionally acquire a browser session from FlareSolverr, Byparr, or both, then replay the returned user-agent and scoped cookies through the bounded URL reader. In dual-provider mode FlareSolverr is always primary and Byparr is attempted only after a busy or transient-unavailable primary. FlareSolverr 3.5.0 and Byparr 2.1.0 were verified on 2026-07-30.
- Intelligent Caching: Both search results and URL content are cached in memory with configurable TTL and least-frequently-used (LFU) eviction, reducing redundant requests.
- SSRF Protection: web_url_read blocks private/internal URLs and redirects by default in all transport modes.
- HTTP Transport: Optional MCP SDK v2 Streamable HTTP mode with opt-in hardening, rate limiting, and bounded stateless compatibility for serverless or horizontally scaled deployments. Modern 2026-07-28 requests and retained legacy clients share the same tool and resource surface.
- HTML Fallback: Optionally parse results from the HTML page for public instances that reject format=json.
- Lite Tools Mode: Minimal tool schemas for local models with small context windows.
- Proxy Support: Global or per-tool HTTP/HTTPS proxies for search and URL-reader traffic.
The verified linux/amd64 images came from multi-architecture manifests
ghcr.io/flaresolverr/flaresolverr:v3.5.0@sha256:139dfee1c6f89249c8d665d1333a42e8ec74ec0a86bc6bb1c8461e10d3a66a47
and
ghcr.io/thephaseless/byparr:2.1.0@sha256:01a46a2865d9a6db5eb8ead04ec0dd33b8fbe233e8565ae70b50d4cc0af4cfb0.
Client cancellation stops local work promptly, but a remote browser may
continue until its configured provider timeout after the HTTP client
disconnects. See browser solver verification.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
SearXNGCommand (node, npx, python, etc.)npxArguments-
Argument 1
-y -
Argument 2
mcp-searxng
Environment-
SEARXNG_URL
YOUR_SEARXNG_INSTANCE_URL
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
-
Argument 1
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Node.js 22 or later is required.
<details>
<summary>NPM (global install)</summary>
npm install -g mcp-searxng
{
"mcpServers": {
"searxng": {
"command": "mcp-searxng",
"env": {
"SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
}
}
}
}
</details>
<details>
<summary>Docker</summary>
Pre-built image:
docker pull isokoliuk/mcp-searxng:latest
Image 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. 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.
</details>
<details>
<summary>Docker Compose</summary>
docker-compose.yml:
```yaml
searxng_web_search
Execute web searches with pagination. Inputs: query (string), pageno (number, optional), time_range (string, optional), language (string, optional), safesearch (string enum, optional), min_score (number, optional), num_results (number, optional), categories (string, optional), engines (string, optional), response_format (string, optional), result_detail (string, optional).
searxng_search_suggestions
Get autocomplete suggestions for refining search queries. Inputs: query (string), language (string, optional).
searxng_instance_info
Discover categories aggregated from reachable configured SearXNG instances. Inputs: includeEngines (boolean, optional), includeDisabled (boolean, optional), category (string, optional), refresh (boolean, optional).
web_url_read
Read URL content as markdown with content-type-aware handling and advanced extraction options. Inputs: url (string), startChar (number, optional), maxLength (number, optional), section (string, optional), paragraphRange (string, optional), readHeadings (boolean, optional).
- searxng_web_search
- Execute web searches with pagination
- Inputs:
- query (string): The search query. This string is passed to external search services.
- pageno (number, optional): Search page number, starts at 1 (default 1)
- time_range (string, optional): Filter results by time range - one of: "day", "week", "month", "year" (default: none)
- language (string, optional): Language code for results (e.g., "en", "fr", "de") or "all" (default: "all")
- safesearch (string enum, optional): Safe search filter level, one of "0" (None), "1" (Moderate), or "2" (Strict). Legacy numeric values 0, 1, and 2 are still accepted for backward compatibility. (default: instance setting)
- min_score (number, optional): Minimum relevance score from 0.0 to 1.0. Results below this score are filtered out.
- num_results (number, optional): Maximum number of results to return, from 1 to 20. SEARXNG_MAX_RESULTS applies as an operator ceiling.
- categories (string, optional): Comma-separated SearXNG categories (e.g. "news", "it,science"). Live /config capabilities are aggregated across reachable instances; prefer searxng_instance_info categories.common for consistent multi-instance results. Known values are trimmed and normalized case-insensitively; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If /config is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default.
- engines (string, optional): Comma-separated SearXNG engine names (e.g. "google,bing,ddg", "semantic scholar"). Live /config capabilities are aggregated across reachable instances; prefer searxng_instance_info engines.common.enabled for consistent multi-instance results. Known values are trimmed and normalized case-insensitively, including engines disabled by default; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If /config is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default.
- response_format (string, optional): Response format, either "text" for formatted agent-readable output or "json" for raw SearXNG JSON with filtered/sliced results. If omitted, SEARXNG_DEFAULT_RESPONSE_FORMAT applies; if unset or invalid, text is used. An explicit response_format always takes precedence.
- result_detail (string, optional): "full" (the default) preserves SearXNG metadata, warnings, provenance, answers, infoboxes, corrections, and suggestions. "compact" returns only title, URL, and the description/content snippet for every result; compact JSON uses exactly the title, url, and content keys. Use full when those research signals matter.
- Clients that explicitly send or auto-inject response_format=text continue to override the operator default. If omitted calls still return text after configuring JSON, inspect the arguments emitted by the MCP client.
Migration: compact text has exactly three lines per result and no cache annotation or preamble. Update line parsers that expect relevance scores or search metadata to request result_detail="full" (or accept compact's three-line records).
Compact deliberately suppresses warnings, provenance, and every other search signal. Full text may add valid optional lines in fixed order: score, engines, category, published date, thumbnail, image source; invalid optional metadata is omitted. Text fields are normalized to single lines. SEARXNG_MAX_RESULT_CHARS truncates result content in compact and full text/JSON responses, including full JSON for existing users who already set the variable; compact text normalizes line separators before applying the cap, while JSON caps the original string value.
With SEARXNG_LITE_TOOLS=true, the Lite schema stays query-only, but explicitly supplied optional overrides such as response_format and result_detail are still validated and honored.
- searxng_search_suggestions
- Get autocomplete suggestions for refining search queries
- Inputs:
- query (string): Partial or complete query to autocomplete.
- language (string, optional): Language code for suggestions (e.g., "en", "fr", "de") or "all" (default: "all")
- searxng_instance_info
- Discover categories aggregated from reachable configured SearXNG instances, optionally include engine names, and inspect defaults, locales, and plugins from the primary reachable instance. Categories—and engines when requested—report common values present on every reachable instance and available values present on at least one reachable instance.
- Inputs:
- includeEngines (boolean, optional): Include enabled engine names in the response. (default: false)
- includeDisabled (boolean, optional): Include disabled engine names when includeEngines is true. (default: false)
- category (string, optional): Filter categories and engines to a single category name.
- refresh (boolean, optional): Bypass the process cache and fetch fresh /config data. (default: false)
- web_url_read
- Read URL content as markdown with content-type-aware handling and advanced extraction options
- Supported readable content:
- HTML (text/html, application/xhtml+xml) is converted to markdown
- JSON (application/json, +json) is pretty-printed in a fenced block
- Plain text, YAML, TOML, XML, and other safe explicit text/ responses are returned as readable fenced text
- PDF (application/pdf) text is extracted in a resource-bounded worker for documents up to 500 pages
- Missing or generic content types are read under the existing size cap; non-binary bodies continue through the HTML-to-markdown path for compatibility
- PDF input and extracted text are each capped at the lower of URL_READ_MAX_CONTENT_LENGTH_BYTES and 16 MiB. OCR is not supported, and scanned/image-only or password-protected PDFs return a short explanation.
- A response declared as PDF must begin with the %PDF- signature; a mismatch usually indicates an interstitial or error page served with the wrong content type.
- PDF parsing has a separate 30-second worker budget after the response body is downloaded. On the direct path, the network fetch and parse take at most the configured fetch budget plus 30 seconds; configured browser-solver preflight and acquisition time is additional.
- At most two PDF extractions run concurrently per MCP process. There is no queue; additional concurrent reads return a busy message and may be retried.
- Other binary, media, archive, and octet-stream downloads are intentionally rejected with a short hint instead of returning raw bytes
- When FLARESOLVERR_URL or BYPARR_URL is configured, an uncached URL is validated and checked by the HEAD size preflight before mcp-searxng attempts browser-session acquisition. With both set, FlareSolverr is attempted first and Byparr is attempted only after a busy slot, network/timeout failure, HTTP 408/429/5xx, or malformed/oversized response. Persistent provider 4xx, cancellation, solution-host validation failure, and solved non-2xx target status stop the chain. If every configured provider is busy or unavailable, one uncached direct fetch runs. Each attempted provider receives the original target URL; challenge success is not guaranteed.
- At default limits, dual-provider mode has an additive maximum of 150 seconds across the initial HEAD preflight, both solver attempts (including response grace), and the final direct fetch.
- Inputs:
- url (string): The URL to fetch and process
- startChar (number, optional): Starting character position for content extraction (default: 0)
- maxLength (number, optional): Maximum number of characters to return
- section (string, optional): Extract content under a specific heading (searches for heading text)
- paragraphRange (string, optional): Return specific paragraph ranges (e.g., '1-5', '3', '10-')
- readHeadings (boolean, optional): Return only a list of headings instead of full content
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"searxng": {
"env": {
"SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
},
"args": [
"-y",
"mcp-searxng"
],
"command": "npx"
}
}
}Linux
{
"env": {
"SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
},
"args": [
"-y",
"mcp-searxng"
],
"command": "npx"
}Macos
{
"env": {
"SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
},
"args": [
"-y",
"mcp-searxng"
],
"command": "npx"
}Windows
{
"env": {
"SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
},
"args": [
"/c",
"npx",
"-y",
"mcp-searxng"
],
"command": "cmd"
}Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
