searxng_instance_info
Discovers capabilities from all reachable configured SearXNG instances via /config, including categories.common/available, engines.common/available, defaults, locales, and plugins.
LABSCO SUMMARY
Search runs on an instance you control, and the results come back readable.
What it takes off you is the search-vendor account: queries go to your own SearXNG, where the engine mix, categories and safe-search level are already what you decided. The reader is the other half — it is content-type aware, so a JSON endpoint, a YAML file and a PDF each come back in a form the model can use rather than as a blob.
What it is
A client for a SearXNG instance you run or choose. Searches go to that instance over its JSON API, so which engines answer and what is enabled are your settings rather than a vendor's. It is a separate process, not a SearXNG plugin.
What you get
- Web results with title, URL and content snippet, paginated, and narrowed by category, engine, language, time range, safe-search level and a minimum score
- SearXNG's own answers, corrections, suggestions and infoboxes ahead of the result list
- Results as agent-readable text or as raw JSON, chosen per call or set as the server default
- Autocomplete suggestions for refining a vague or partial query before searching
- The capabilities of every reachable configured instance — common and available categories and engines, defaults, locales and plugins
- Any URL read back as Markdown, content-type aware: HTML becomes Markdown, JSON is pretty-printed, and plain text, YAML, TOML and XML come back as fenced text
- PDF text extraction with bounds on input, output, page count, time, concurrency and memory
- Section, heading, paragraph-range and character-offset controls, for reading part of a long page
- Several instances behind one SEARXNG_URL: searches fail over in order, or fan out to every healthy replica in parallel and merge
- Search results and fetched pages cached in memory, with a TTL and least-frequently-used eviction you configure
- Private and internal addresses refused by the URL reader, redirects included, in every transport mode
- A lite tool schema for local models whose context window cannot carry the full one
Requirements
npx on your PATH and a SearXNG instance to point SEARXNG_URL at — that is the only required setting, and it takes a semicolon-separated list if you have replicas. The instance has to answer JSON: a public one you do not control usually refuses, and SEARXNG_HTML_FALLBACK=true then retries the search against the ordinary HTML page, with relevance scores and engine names missing from what comes back. AUTH_USERNAME and AUTH_PASSWORD cover an instance behind basic auth. Scanned PDFs needing OCR are out of reach.
Setup effort
One command — npx -y mcp-searxng
USE CASES
01
Researching a question without handing it to a search vendor
Query your own instance, then read the pages worth reading as Markdown in the same thread.
02
Getting a vague question into a searchable shape
Pull autocomplete suggestions from the instance first, then search with the phrasing that actually returns results.
03
Working out what your instance can actually search
Read the categories, engines, locales and plugins the instance reports, so the filters you pass are ones it supports.
04
Reading one section of a long document
Fetch by heading, paragraph range or character offset instead of pulling the whole page into context.
05
Pulling text out of a PDF you found
The reader extracts it under explicit bounds on pages, output size, time and memory — so a huge file fails fast rather than hanging.
4 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
searxng_search_suggestions
Returns autocomplete suggestions from the configured SearXNG instance. Use this to refine vague or partial queries before searching.
searxng_web_search
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. To read the full text of a result URL, follow up with web_url_read.
web_url_read
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.
BEFORE YOU INSTALL
What to know first
Tools you get
4 tools when we connected. Setting result_detail="compact" suppresses warnings and provenance, and web_url_read rejects binary, media and archive downloads. SEARXNG_LITE_TOOLS=true simplifies input schemas without removing any tool.
Requires
- npx on PATH
- Node.js 22 or later
CONTEXT COST
Light Standing cost
Rated by the size of the 4 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y mcp-searxngMCP Clients
Claude Desktop — stdio, Cursor — stdio, Windsurf — stdio, Cline — stdio
JSON
{
"mcpServers": {
"searxng": {
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "<YOUR_SEARXNG_URL>"
}
}
}
}<YOUR_SEARXNG_URL> is your SearXNG base URL (the client passes it to the server as SEARXNG_URL).
Windsurf — HTTP
HTTP client entries do not start mcp-searxng: deploy it separately in Streamable HTTP mode first (for example the project's Docker image with MCP_HTTP_PORT, MCP_HTTP_AUTH_TOKEN and SEARXNG_URL set). <YOUR_SERVER_URL> is that server's address, in front of /mcp. The token is the same secret as its MCP_HTTP_AUTH_TOKEN — export it as MCP_SEARXNG_TOKEN before launching Windsurf:
WINDSURF — HTTP · JSON
{
"mcpServers": {
"searxng-http": {
"serverUrl": "<YOUR_SERVER_URL>/mcp",
"headers": {
"Authorization": "Bearer ${env:MCP_SEARXNG_TOKEN}"
}
}
}
}Cline — HTTP
HTTP client entries do not start mcp-searxng: deploy it separately in Streamable HTTP mode first (for example the project's Docker image with MCP_HTTP_PORT, MCP_HTTP_AUTH_TOKEN and SEARXNG_URL set). <YOUR_SERVER_URL> is that server's address, in front of /mcp, and <YOUR_TOKEN> is the same secret as its MCP_HTTP_AUTH_TOKEN; keep this file out of version control:
CLINE — HTTP · JSON
{
"mcpServers": {
"searxng-http": {
"type": "streamableHttp",
"url": "<YOUR_SERVER_URL>/mcp",
"headers": {
"Authorization": "Bearer <YOUR_TOKEN>"
},
"disabled": false,
"autoApprove": []
}
}
}Claude Code
CLAUDE CODE · TERMINAL
claude mcp add --scope user --env SEARXNG_URL=<YOUR_SEARXNG_URL> --transport stdio searxng -- npx -y mcp-searxng<YOUR_SEARXNG_URL> is your SearXNG base URL (the client passes it to the server as SEARXNG_URL).
Codex
CODEX · TOML
[mcp_servers.searxng]
command = "npx"
args = ["-y", "mcp-searxng"]
[mcp_servers.searxng.env]
SEARXNG_URL = "<YOUR_SEARXNG_URL>"<YOUR_SEARXNG_URL> is your SearXNG base URL (the client passes it to the server as SEARXNG_URL).
VS Code
VS CODE · JSON
{
"servers": {
"searxng": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "<YOUR_SEARXNG_URL>"
}
}
}
}<YOUR_SEARXNG_URL> is your SearXNG base URL (the client passes it to the server as SEARXNG_URL).
OpenCode
OpenCode V2 stores servers under mcp.servers in opencode.json, which is what this block uses. OpenCode's non-V2 configuration (opencode.ai/docs/mcp-servers) puts the server entry directly under mcp, without the servers level:
OPENCODE · JSON
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"searxng": {
"type": "local",
"command": [
"npx",
"-y",
"mcp-searxng"
],
"environment": {
"SEARXNG_URL": "<YOUR_SEARXNG_URL>"
}
}
}
}
}Any MCP client — Docker
ANY MCP CLIENT — DOCKER · JSON
{
"mcpServers": {
"searxng-docker": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"SEARXNG_URL",
"isokoliuk/mcp-searxng:latest"
],
"env": {
"SEARXNG_URL": "<YOUR_SEARXNG_URL>"
}
}
}
}<YOUR_SEARXNG_URL> is your SearXNG base URL (the client passes it to the server as SEARXNG_URL).
