Skip to main content
Glama
atomlong

mcp-searxng

by atomlong
OverviewSchemaRelated ServersScoreDiscussions
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.1/5.0
Behavior4/5

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

Annotations provide readOnlyHint and openWorldHint. The description adds caching behavior (refresh parameter) and filtering options, which supplements the annotations without contradiction.

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, well-structured sentence that front-loads the main purpose and details. Every word is informative, with no redundancy.

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?

Given the lack of output schema, the description adequately lists the data returned (categories, engines, defaults, etc.). Combined with annotations, the context is sufficient for usage.

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. The tool description reiterates the refresh bypass cache behavior but does not add significant new meaning beyond the 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 uses specific verbs ('Discovers capabilities') and identifies the exact resource (SearXNG instances via /config). It lists the data returned and clearly distinguishes from sibling search/read tools.

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 does not explicitly state when to use this tool vs alternatives. While the purpose is clear, it lacks when-not guidance or references to sibling tools.

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/5.0
Behavior3/5

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

Annotations already declare readOnlyHint and openWorldHint, so the description adds limited behavioral context. It confirms the tool returns suggestions but doesn't elaborate on traits like rate limits or instance-specific behavior.

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 with no wasted words. The primary action is front-loaded, and the usage guidance is succinct.

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 simple tool with two parameters and no output schema, the description covers the return value and use case. It does not describe the return format, but given the simplicity, this is acceptable.

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 description coverage is 100%, so the schema fully documents both parameters. The description adds no additional semantics beyond what the schema provides.

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's action ('Returns autocomplete suggestions') and resource ('SearXNG instance'). It distinguishes from siblings like searxng_web_search by focusing on refinement before searching.

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

Usage Guidelines4/5

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

Explicitly advises using the tool to 'refine vague or partial queries before searching', providing clear context. Does not include explicit when-not or alternatives, but the sibling tools naturally differentiate.

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. Dates show when Glama detected each change.

  1. 4 tool updatesv1.8.0
    • First observedsearxng_instance_info
    • First observedsearxng_search_suggestions
    • First observedsearxng_web_search
    • First observedweb_url_read
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0
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

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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
    166
    54
    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
    22
    4
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/atomlong/mcp-searxng'

If you have feedback or need assistance with the MCP directory API, please join our Discord server