Skip to main content
Glama
atomlong

mcp-searxng

by atomlong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

🔍 SearXNG MCP Server

Private web search for AI assistants — connect any SearXNG instance to Claude, Cursor, and more.

GitHub Stars npm version npm downloads Docker Pulls License: MIT OpenSSF Scorecard OpenSSF Best Practices mcp-searxng MCP server GitHub MCP Registry

An MCP server that integrates the SearXNG API, giving AI assistants web search capabilities.

✨ Featured in the GitHub MCP Registry.

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.

Related MCP server: SearXNG MCP Server

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?

Brave MCP

Exa MCP

Firecrawl MCP

mcp-searxng

Web Search

✓

✓

✓

✓

Read URL

✗

✓

✓

✓

Pagination

✗

✗

✓

✓

Self-hosted

✗

✗

Partial

✓

Privacy

✗

✗

✗

✓

Free / No API key

✗

✗

✗

✓

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 and convert the content from a URL to markdown with advanced content extraction options

    • 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

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: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.

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=YOUR_SEARXNG_INSTANCE_URL
      # Add optional variables as needed — see CONFIGURATION.md

MCP client config:

{
  "mcpServers": {
    "searxng": {
      "command": "docker-compose",
      "args": ["run", "--rm", "mcp-searxng"]
    }
  }
}

By default the server uses STDIO. Set MCP_HTTP_PORT to enable HTTP mode:

{
  "mcpServers": {
    "searxng-http": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "MCP_HTTP_PORT": "3000"
      }
    }
  }
}

Endpoints: POST/GET/DELETE /mcp (MCP protocol), GET /health (health check)

Test it:

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng
curl http://localhost:3000/health

Configuration

Set SEARXNG_URL to your SearXNG instance URL. For failover, set it to semicolon-separated interchangeable replica URLs. 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

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.

Available Tools

4 tools
searxng_instance_infoA
Read-only

Discovers capabilities from all reachable configured SearXNG instances via /config, including categories.common/available, engines.common/available, defaults, locales, and plugins.

ParametersJSON Schema
NameRequiredDescriptionDefault
refreshNoBypass the process cache and fetch fresh /config data.
categoryNoFilter categories and engines to a single category name.
includeEnginesNoInclude enabled engine names in the response.
includeDisabledNoInclude disabled engine names when includeEngines is true.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds context beyond the readOnlyHint annotation by noting it fetches from 'all reachable configured instances' and describes the data categories returned. It does not mention caching behavior despite the refresh parameter, but the core behavioral traits (read-only, network-dependent) are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the action ('Discovers capabilities') and uses a compact, informative list for data categories. Every phrase contributes meaning without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with no output schema, the description adequately covers its purpose and the data content it returns. It lacks explicit treatment of caching (hinted at by the refresh parameter) and behavior when instances are unreachable, which would be useful but are not critical for basic invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions, so the tool description does not need to explain parameters. The description's list of output categories (e.g., categories.common/available) loosely relates to the 'category' filter but does not explicitly connect them, adding only marginal semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'discovers' and names the resource: capabilities of SearXNG instances. It enumerates the exact content categories (categories, engines, defaults, locales, plugins), making it distinct from sibling tools like searxng_web_search and searxng_search_suggestions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you need to inspect instance capabilities, but it does not explicitly state when to choose this over sibling search tools or provide exclusions. The context is inferred rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

searxng_search_suggestionsA
Read-only

Returns autocomplete suggestions from the configured SearXNG instance. Use this to refine vague or partial queries before searching.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesPartial or complete query to autocomplete.
languageNoLanguage code for suggestions (e.g., 'en', 'fr', 'de') or 'all'. Default: all.all

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and determinism profile. The description adds that results come from the configured instance, implying external dependency, but doesn't disclose rate limits or response format. With annotations doing the heavy lifting, 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose and immediately followed by usage guidance. No filler or repetition of schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only suggestion tool with two well-documented parameters and no output schema, the description fully conveys purpose and usage. Annotations cover behavioral constraints, making this complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with descriptions for both query and language including default values. The description's 'autocomplete suggestions' adds context but does not materially enhance what the schema already provides, so baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Returns autocomplete suggestions from the configured SearXNG instance' – a specific verb, resource, and source. The name and description distinguish it from sibling tools like web_search and instance_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this to refine vague or partial queries before searching', providing clear when-to-use context and implying it is a precursor to web search. This is unambiguous guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

web_url_readA
Read-only

Fetches a URL and returns its text content converted to markdown. 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL
sectionNoExtract content under a specific heading (searches for heading text)
maxLengthNoMaximum number of characters to return
startCharNoStarting character position for content extraction (default: 0)
readHeadingsNoReturn only a list of headings instead of full content
paragraphRangeNoReturn specific paragraph ranges (e.g., '1-5', '3', '10-')

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint and openWorldHint. Description adds behavioral details: three modes, error handling (returns error string if unreachable), and mutual exclusion. It's transparent about what the tool does but doesn't cover all edge cases (e.g., combining multiple filtering params other than readHeadings).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single but well-structured paragraph that enumerates modes clearly. Every sentence adds value with no redundancy. Front-loaded with main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main functionality, modes, error handling, and relation to sibling tool. No output schema, but return type (text/markdown) is implied. Minor gap: doesn't specify behavior when multiple filtering params are combined beyond readHeadings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are documented. The description adds significant meaning by grouping parameters into modes and explaining relationships (e.g., omit filtering for full content, set section for extraction, readHeadings for headings). It clarifies mutex conditions beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches a URL and converts content to markdown, with three distinct modes. It distinguishes from sibling tools (search tools) by specifying it's for reading individual URLs after a search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use after searxng_web_search to read full content of result URLs. Describes three modes and their parameter usage, including mutual exclusivity of readHeadings. Provides guidance on pagination with startChar/maxLength.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.8.0
    • First observedsearxng_instance_info
    • First observedsearxng_search_suggestions
    • First observedsearxng_web_search
    • First observedweb_url_read
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: instance info, search suggestions, web search, and URL reading. There is no overlap or ambiguity.

Naming Consistency4/5

Three tools follow the 'searxng_' prefix with verb_noun pattern, but 'web_url_read' breaks the prefix convention. Still mostly consistent and readable.

Tool Count5/5

Four tools is well-scoped for a search server, covering key functionalities without unnecessary bloat or gaps.

Completeness5/5

The tool set covers the full workflow: discovering capabilities, refining queries, searching, and reading results. No obvious gaps for the intended purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • SearXNG MCP Server

    pwilkin
    A
    license
    A
    quality
    C
    maintenance
    An MCP server that allows searching through public SearXNG instances by parsing HTML content into JSON results, enabling metasearch capabilities without requiring JSON API access.
    1
    43 npm
    55
    MIT

  • SearXNG MCP Server

    tobioffice
    A
    license
    B
    quality
    D
    maintenance
    An MCP server that integrates with the SearXNG API to provide comprehensive web search capabilities with features like time filtering, language selection, and safe search. It also enables users to fetch and convert web content from specific URLs into markdown format.
    2
    6 npm
    4
    MIT