SearXNG Public

What is mcp-searxng-public?

mcp-searxng-public is a Model Context Protocol (MCP) server designed to retrieve search results from public SearXNG instances. Unlike other SearXNG MCP servers that rely on JSON output, this project specifically parses HTML content from these instances, converting it into a structured JSON format. This approach addresses the limitation where most public SearXNG servers do not expose a direct JSON output, ensuring broader compatibility and functionality.

How to use mcp-searxng-public?

To use mcp-searxng-public, you first need to install it via npm:

npm install mcp-searxng-public

Once installed, you can configure it to run as a server. A typical run configuration for the server, for example, with Cursor, involves setting up environment variables like SEARXNG_BASE_URL to specify the SearXNG instances to query and DEFAULT_LANGUAGE for the search language. You can use any servers from searx.space as your selected instances.

Example stdio run configuration:

{
      "name": "SearXNGScraper",
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-searxng-public"],
      "capabilities": {
        "tool-calls": true
      },
      "env": {
        "SEARXNG_BASE_URL": "https://searx.be;https://searx.tiekoetter.com;https://opnxng.com;https://searxng.world;https://searx.oloke.xyz;https://seek.fyi",
        "DEFAULT_LANGUAGE": "en"
      }
}

The server exposes a single endpoint: search. This endpoint accepts the following arguments:

• query: The search query string.
• time_range (optional): Specifies the time range for the search results (e.g., day, month, year), adhering to the SearXNG search API specification.
• language (optional): The language code for the search (e.g., en, es, fr). If not provided, it defaults to the DEFAULT_LANGUAGE environment variable.

The server returns an array of JSON objects, each containing the url and summary of a search result.

Key Features of mcp-searxng-public

• HTML Parsing: Capable of parsing HTML content from public SearXNG instances to extract search results, overcoming the lack of direct JSON output.
• Fallback Support: Can be configured to use multiple public SearXNG servers, with fallback support if one instance fails.
• Configurable SearXNG Instances: Allows users to specify their preferred SearXNG instances via environment variables.
• Language Support: Supports searching in various languages.
• Time Range Filtering: Enables filtering search results by time range.
• JSON Output: Provides structured JSON output for easy integration with other applications.

Use Cases of mcp-searxng-public

• Automated Data Collection: Ideal for applications requiring automated collection of search results from SearXNG.
• Building Custom Search Interfaces: Can be used as a backend for custom search interfaces that leverage public SearXNG instances.
• Research and Analysis: Useful for researchers and data analysts who need to programmatically access and process search results.
• Integration with AI Models: As an MCP server, it can be integrated with AI models and tools that require structured search data.

FAQ from mcp-searxng-public

Q: Why does this server parse HTML instead of using JSON output? A: Most public SearXNG servers do not expose a direct JSON output. This server parses HTML to ensure compatibility and functionality across a wider range of public instances.

Q: Can I use any public SearXNG instance with this server? A: Yes, you can use any servers listed on searx.space by configuring the SEARXNG_BASE_URL environment variable.

Q: How do I specify the search language? A: You can specify the search language using the language argument in the search endpoint or by setting the DEFAULT_LANGUAGE environment variable.

Q: What kind of output does the server provide? A: The server returns an array of JSON objects, with each object containing the url and summary of a search result.

mcp-searxng-public

An MCP server that queries public SearXNG instances, parsing HTML contents into a JSON result

Rationale

All the MCP servers for SearXNG that I've seen use "json" as the output format. While that is certainly a faster way to code a SearXNG MCP server, it will make it fail on virtually all public servers since they don't expose the JSON format.

This server will read from up to three public SearXNG servers (using one as main and the others as fallback) and will parse the results into JSON.

Installation

Install via npm install mcp-searxng-public.

If the server is installed, the run configuration is:

{
      "name": "SearXNGScraper",
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-searxng-public"],
      "capabilities": {
        "tool-calls": true
      },
      "env": {
        "SEARXNG_BASE_URL": "https://searx.be;https://searx.tiekoetter.com;https://opnxng.com;https://searxng.world;https://searx.oloke.xyz;https://seek.fyi",
        "DEFAULT_LANGUAGE": "en"
      }
}

(you can use any servers from https://searx.space/ as your selected servers)

For use with Cursor, the MCP definition is as follows:

{
  "SearXNGScraper": {
    "command": "npx",
    "args": ["mcp-searxng-public"],
    "capabilities": {
      "tool-calls": true
    },
    "env": {
      "SEARXNG_BASE_URL": "https://searx.be;https://searx.tiekoetter.com;https://opnxng.com",
      "DEFAULT_LANGUAGE": "en"
    }
  }
}

Note: You may need to adjust the env variables, particularly SEARXNG_BASE_URL, to point to your preferred SearXNG instances. The DEFAULT_LANGUAGE can also be set as needed.

Usage

The server exposes one endpoint: search. The endpoint takes three arguments:

• query - the search query
• time_range (optional) - which takes a time range parameter according to the https://docs.searxng.org/dev/search_api.html spec (day, month or year).
• language (optional) - the language code for the search (e.g., en, es, fr). If not provided, it defaults to the value of the DEFAULT_LANGUAGE environment variable. If neither is set, no language parameter is sent to SearXNG.

Returned is an array of objects:

[
      {
        "url": "https://github.com/searxng/searxng",
        "summary": "You can start SearXNG using make run in the terminal or by pressing Ctrl+Shift+B"
      },
      {
        "url": "https://searx.bndkt.io/",
        "summary": "Powered by searxng - 2025.3.22+5986629c6 — a privacy-respecting, open metasearch engine Source code | Issue tracker | Engine stats | Public instances | Contact instance maintainer"
      },
      {
        "url": "https://docs.searxng.org/"
        "summary": "SearXNG is a free internet metasearch engine which aggregates results from up to 243 search services. Users are neither tracked nor profiled. Additionally, SearXNG can be used over Tor …"
      }
      {
        "url": "https://en.wikipedia.org/wiki/SearXNG",
        "summary": "SearXNG is federated, and as such is hosted by several instances, public and private. Private instances are hosted on a local network, or run on the user's desktop computer itself, and are …"
      }
]