Skip to main content
Glama
FivePebblesGPT

SearXNG MCP Server

by FivePebblesGPT
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Deep Re SearXNG

This fork combines the mcp-searxng v2.9.0 server with a local SearXNG/Valkey Compose stack, repo-scoped research skills, a read-only researcher agent and result validation. Node.js 22+ is required for local Node development. See NOTICE.md for source revisions.

Bundled stack and deep research

git clone https://github.com/FivePebblesGPT/deep-re-searxng.git
cd deep-re-searxng
docker compose -f compose.yaml up -d --build
curl --fail http://127.0.0.1:3000/health

Follow Deep research setup for the six skills, agent configuration, Python validation and workflow. The default compose.yaml starts SearXNG, Valkey and this fork's MCP HTTP service; docker-compose.yml is the separate upstream MCP-only STDIO example and requires an existing SearXNG URL.

The server reference below is retained from upstream. Its NPX/Docker recipes install the upstream server distribution, not this fork's source-only research skills. Use the bundled-stack instructions above for the combined toolset.

Related MCP server: Google Search MCP Server

Upstream server reference

🔍 SearXNG MCP Server

Privacy-respecting web search for AI assistants — use an operator-controlled or trusted SearXNG instance with 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

You need an existing SearXNG instance with JSON search enabled. This project connects an MCP client to SearXNG; it does not install SearXNG. Use an instance you operate or trust. Start with the self-hosted or public-instance guide if needed.

Choose how to connect:

Your setup

Start here

Client starts the server locally

Install Node.js 22 or later, then use the NPX example below or your client recipe.

Client starts a Docker container

Use the Docker/STDIO recipe in Installation.

You have an independently running HTTP service

Use your client's HTTP recipe with the full /mcp URL.

You need to operate an HTTP service

Follow the HTTP server guide.

For clients using mcpServers JSON (such as Claude Desktop), add:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": { "SEARXNG_URL": "https://search.example.com" }
    }
  }
}

Replace the example URL with your SearXNG base URL. Other clients use different configuration shapes: choose your client recipe. Leave MCP_HTTP_PORT unset for local STDIO. Docker also needs environment forwarding into the container.

Reload the client, inspect its MCP tool inventory, then ask it to search for SearXNG documentation. A simple tool call is searxng_web_search with {"query":"SearXNG"}. Discovery alone does not test SearXNG connectivity. If the call fails, start with troubleshooting.

Features

  • Search with pagination, filters, direct answers and full or compact text/JSON output.

  • Read HTML, structured text and bounded PDF text; inspect headings or selected sections.

  • Discover instance capabilities and get query suggestions.

  • Optional replica failover/fan-out, HTML fallback, caching, proxies and browser solvers.

  • Local STDIO or Streamable HTTP, with static bearer and optional OAuth protection.

See the tool guide for capabilities and limits, configuration reference for settings, and historical deployment measurements for bounded resource-planning evidence.

Why mcp-searxng?

As of 2026-07-29, the capability comparison below reflects the official Brave MCP, Exa MCP, and Firecrawl MCP projects. “Pagination” means an exposed page or offset control. “Self-hosted” means the search service can run under your control. “Free / No API key” means this MCP server does not require a paid search-vendor API key; you still operate or select the underlying SearXNG instance.

Brave MCP

Exa MCP

Firecrawl MCP

mcp-searxng

Web Search

âś“

âś“

âś“

âś“

Read URL

âś—

âś“

âś“

âś“

Pagination

âś“

âś—

âś“

âś“

Self-hosted

âś—

âś—

Partial

âś“

Free / No API key

âś—

âś—

âś—

âś“

Privacy depends on the SearXNG deployment. An operator-controlled instance can avoid trusting a third-party search operator, while a public instance receives the query and may log it. SearXNG and this MCP integration do not by themselves provide anonymity.

How It Works

MCP client → mcp-searxng → SearXNG → search engines

The client either starts its own STDIO process or connects to an HTTP service. SEARXNG_URL identifies the SearXNG service, not the MCP endpoint. URL reading fetches the selected website directly. A semicolon-separated replica list is supported for interchangeable SearXNG deployments; see replica configuration.

STDIO is the default. Legacy Streamable HTTP sessions are stateful by default: clients should send DELETE /mcp when finished, then reinitialize if a later request receives HTTP 404 for the terminated session. Modern HTTP requests and the MCP_HTTP_STATELESS=true legacy mode are sessionless; see HTTP transport configuration.

Tools

Tool

Use it to

searxng_web_search

Find sources and refine results

searxng_search_suggestions

Complete or refine a query

searxng_instance_info

Inspect categories, engines and defaults

web_url_read

Read a known URL as text/Markdown

The tool guide contains examples and the full parameter reference. The optional research workflow explains how to inspect sources and cite evidence.

Installation

The project-maintained distribution methods are npm (including npx) and Docker. Additional package formats, including Nix, can be maintained separately by the community.

For NPX and npm installs, Node.js 22 or later is required. The Docker image includes its Node.js runtime.

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. 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. Safe rendered HTML and explicit Byparr PDF content are read directly; ambiguous content uses guarded replay, with bounded failover for eligible read failures. 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.

docker-compose.yml:

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=${SEARXNG_URL:?Set SEARXNG_URL in the environment}
      # Add optional variables as needed — see CONFIGURATION.md

The tracked Compose file is intentionally STDIO-only and publishes no network ports; MCP clients launch it with an absolute Compose-file path and docker compose run --rm -T, not docker compose up. The -T flag prevents pseudo-TTY allocation so MCP JSON-RPC stays on raw standard input and output. Compose fails before launch unless the MCP client supplies SEARXNG_URL.

MCP client config:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/docker-compose.yml",
        "run", "--rm", "-T", "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

If you previously used the tracked file as an HTTP service on port 8080, put the HTTP settings in an untracked docker-compose.override.yml:

services:
  mcp-searxng:
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - MCP_HTTP_PORT=8080
      - MCP_HTTP_HOST=0.0.0.0

Here 0.0.0.0 is the container-side bind address; the host-side port remains loopback-only. This override has no authentication and is only a temporary single-host migration path. Before adding co-located containers or exposing the service beyond the local machine, follow the hardened deployment guidance.

HTTP Transport

Run HTTP independently, then connect the client. See the HTTP server guide for local checks, static bearer authentication, OAuth requirements and deployment verification.

Configuration

For the default local setup, SEARXNG_URL is the required setting. Optional modes such as hardened HTTP and OAuth have companion requirements. Use the configuration reference for environment variables, defaults, caching, timeouts, proxies, TLS, and limits.

Optional MCP OAuth

An HTTP deployment can use OAuth with an external authorization provider. See authentication choices. Static bearer authentication and SearXNG Basic Auth protect different connections.

Troubleshooting

Symptom

Next check

Server absent or disconnected

Client/process startup

HTTP auth, session or proxy error

HTTP connection

Tools appear but search fails

SearXNG connection

Empty, poor or stale results

Filters, upstream metadata and cache

URL/PDF failure or timeout

URL reading

403 Forbidden from SearXNG

JSON output may be disabled, or an access-control layer may have denied the request. Follow the direct checks before changing settings. A working browser page does not prove the JSON API works.

Can't enable JSON? (HTML fallback)

SEARXNG_HTML_FALLBACK=true can retry 403/404/non-JSON search responses as HTML. Parsing is best-effort and metadata is limited; compact output omits fallback markers. Read the public-instance guidance before enabling it on a service you do not control.

For a bug report, collect a minimal reproduction and relevant errors.

Documentation

Configure search for useful coverage with tested upstream settings, specialist engine routes and MCP output controls. The deployment recipe includes a private Compose stack and optional browser providers, with dated results and known failures.

Find a guide by task. These links open current main-branch documentation. Unreleased behavior is labeled; consult the matching Git tag when investigating an older version.

Contributing

See CONTRIBUTING.md.

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.

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.

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

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.8/5.0
Behavior5/5

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

Annotations provide readOnlyHint and openWorldHint, but the description adds extensive behavioral detail: content-type conversion rules, PDF extraction limits, binary rejection, FlareSolverr/Byparr fallback logic, modes, and error return behavior. This far exceeds what annotations alone communicate, with no contradictions.

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

Conciseness4/5

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

The description is long but each sentence contributes necessary detail. It is front-loaded with the primary purpose and then branches into content types, limitations, modes, and usage. The solver fallback details are somewhat verbose and could be trimmed without losing core guidance, preventing a perfect score.

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?

With no output schema, the description adequately explains return format (markdown, fenced text, error string) and covers all major usage aspects: modes, pagination, unsupported types, and integration with the search tool. This makes it self-sufficient for an AI agent.

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 covers all parameters 100%, so baseline is 3. The description adds value by explaining how parameters combine into three modes (full content with startChar/maxLength, section extraction, readHeadings) and notes mutual exclusivity. However, paragraphRange is not mentioned in the description, so it doesn't fully elaborate every parameter.

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 first sentence clearly states 'Fetches a URL and returns readable content as markdown,' identifying the specific verb and resource. It distinctly differentiates from sibling tools (searxng_web_search, suggestions, instance info) which are search-oriented, not content retrieval.

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 states 'Use after searxng_web_search to read the full content of individual result URLs,' providing clear when-to-use guidance. Also lists exclusions (binary, media, OCR not supported) which inform when not to use.

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 updatesv2.9.0
    • First observedsearxng_instance_info
    • First observedsearxng_search_suggestions
    • First observedsearxng_web_search
    • First observedweb_url_read
Deploy Server
Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct role: web search, autocomplete suggestions, instance capability discovery, and URL content reading. The descriptions explicitly guide follow-up workflows, making misselection unlikely.

Naming Consistency4/5

Three tools share the predictable `searxng_` prefix and snake_case, but `web_url_read` breaks that prefix pattern. The naming is still readable and mostly consistent.

Tool Count5/5

Four tools is well-scoped for a SearXNG integration: search, suggestions, instance info, and content fetching. Each earns its place without redundancy.

Completeness4/5

The surface covers the main search workflow end-to-end, including query refinement and reading result content. Some advanced search modes may be handled via parameters rather than dedicated tools, leaving only minor gaps.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Tavily Web Search MCP Server

    debanshd
    F
    license
    C
    quality
    D
    maintenance
    Enables web search capabilities through the Tavily API via the Model Context Protocol. Allows users to perform web searches and retrieve information from the internet through natural language queries.
    5
    -

  • Google Search MCP Server

    jspv
    A
    license
    A
    quality
    D
    maintenance
    Enables users to perform Google Custom Search queries through the Model Context Protocol. Requires Google API credentials and Custom Search Engine configuration for web search functionality.
    1
    MIT

  • SearXNG-MCP

    BrandonStudio
    A
    license
    A
    quality
    C
    maintenance
    Provides a bridge between AI assistants and SearXNG, a privacy-respecting metasearch engine, enabling web searches and engine discovery via the Model Context Protocol.
    2
    64 npm
    2
    Apache 2.0

  • yacy-mcp

    koosty
    A
    license
    A
    quality
    C
    maintenance
    Enables AI applications to perform web searches using a YaCy search engine instance through the Model Context Protocol.
    1
    MIT