ihor-sokoliuk/mcp-searxng

Quick Start

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Replace YOUR_SEARXNG_INSTANCE_URL with the URL of your SearXNG instance (e.g. https://searxng.example.com). You can also provide interchangeable replicas as a semicolon-separated list, e.g. https://one.example.com;https://two.example.com.

Features

• Web Search: General queries, news, articles, with pagination.
• Instance Failover: Configure multiple interchangeable SearXNG replicas in SEARXNG_URL; searches fail over by default and can optionally fan out in parallel.
• Structured Search Output: Choose formatted text or raw SearXNG-shaped JSON with response_format.
• Direct Answers & Metadata: Text results surface SearXNG answers, corrections, suggestions, and infoboxes before result lists.
• 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: Advanced content extraction with pagination, section filtering, and heading extraction.
• Intelligent Caching: URL content is cached with TTL (Time-To-Live) to improve performance and reduce redundant requests.
• Pagination: Control which page of results to retrieve.
• Time Filtering: Filter results by time range (day, week, month, year).
• Language Selection: Filter results by preferred language.
• Safe Search: Control content filtering level for search results.
• Relevance Filtering: Filter out low-scoring search results with min_score.

Why mcp-searxng?

How It Works

mcp-searxng is a standalone MCP server — a separate Node.js process that your AI assistant connects to for web search. It queries one SearXNG instance, or a semicolon-separated list of interchangeable SearXNG replicas, via the HTTP JSON API.

Not a SearXNG plugin: This project cannot be installed as a native SearXNG plugin. Point it at any existing SearXNG instance, or interchangeable replica list, by setting SEARXNG_URL.

AI Assistant (e.g. Claude)
        │  MCP protocol
        ▼
  mcp-searxng  (this project — Node.js process)
        │  HTTP JSON API  (SEARXNG_URL)
        ▼
  SearXNG instance(s)

Tools

• 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. (default: "text")

• 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, engines, defaults, locales, and plugins exposed by all reachable configured SearXNG instances. The response reports 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
    • Missing or generic content types are read under the existing size cap; non-binary bodies continue through the HTML-to-markdown path for compatibility
  • Binary, media, archive, PDF, and octet-stream downloads are intentionally rejected with a short hint instead of returning raw bytes
  • 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

Installation

Configuration

Set SEARXNG_URL to your SearXNG instance URL. For Basic Auth, embed credentials per instance, for example https://user:[email protected]. For failover, set it to semicolon-separated interchangeable replica URLs; each entry can carry its own credentials. Set SEARXNG_FANOUT=true to query all healthy replicas in parallel and merge results. All other variables are optional.

Full environment variable reference: CONFIGURATION.md

Troubleshooting

If HTTPS requests fail behind a TLS-inspecting corporate proxy with certificate errors, see TLS / Corporate CA.

403 Forbidden from SearXNG

Your SearXNG instance likely has JSON format disabled. Edit settings.yml (usually /etc/searxng/settings.yml):

search:
  formats:
    - html
    - json

Restart SearXNG (docker restart searxng) then verify:

curl 'http://localhost:8080/search?q=test&format=json'

You should receive a JSON response. If not, confirm the file is correctly mounted and YAML indentation is valid.

See also: SearXNG settings docs · discussion

Can’t enable JSON? (HTML fallback)

If you must use a public instance you don’t control and it rejects format=json (the 403 above), set the opt-in flag instead of editing the server:

"SEARXNG_HTML_FALLBACK": "true"

A search that gets a 403/404 or a non-JSON response is then retried automatically without format=json and parsed from the regular HTML results page.

• On success: you get normal results (title, URL, snippet). They are marked sourceFormat: "html" in JSON mode, and text mode adds the line “Note: Results parsed from SearXNG HTML fallback; metadata is limited.” Relevance scores and engine names are not available from HTML.
• On failure: parsing is best-effort and varies by the instance’s theme/version, so some results may be missed or sparse. If the HTML page itself also fails — still blocked, rate-limited (429), auth (401), or 5xx — the original error is surfaced unchanged. The fallback only triggers on 403/404/non-JSON, never on auth or network errors.

Enabling JSON on an instance you control (above) remains the recommended setup — the fallback is a compatibility aid, not a replacement.

Contributing

See CONTRIBUTING.md

Star History

License

MIT — see LICENSE for details.