Noureddine RAMDI / mcp-searxng: bridging AI assistants with private SearXNG-powered web search

Created Mon, 04 May 2026 10:23:02 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
971 Words
github-stars typescript node.js mcp searxng ai-assistant docker

ihor-sokoliuk/mcp-searxng

mcp-searxng is a practical tool for AI developers who want to integrate web search capabilities into their MCP-compatible assistants without relying on proprietary search APIs. It acts as a standalone MCP server proxy that connects any AI client using the Model Context Protocol (MCP) to a self-hosted SearXNG metasearch instance. This setup provides private, flexible, and extendable web search and content extraction features driven entirely by open-source software.

what mcp-searxng does and how it works

At its core, mcp-searxng is a Node.js server that implements the MCP protocol to expose search and URL reading tools to AI clients. It bridges SearXNG’s JSON API—SearXNG being a popular open-source metasearch engine that aggregates results from multiple search engines—into the MCP world.

The server exposes two main tools:

  • searxng_web_search: Enables paginated web search queries with filtering options, allowing the AI assistant to retrieve search results incrementally.
  • web_url_read: Provides advanced extraction of URL content, including the ability to filter specific sections and cache results to optimize repeated accesses.

Architecturally, mcp-searxng runs as a separate process and supports two transport modes for communicating with the AI client:

  • STDIO transport: The default mode where the server communicates over standard input/output streams.
  • HTTP transport: Optionally enabled by setting an environment variable, allowing the server to listen on a specified port for HTTP requests.

This flexibility means that mcp-searxng can fit into various deployment scenarios, from local desktop clients to containerized environments.

The server itself connects to any existing SearXNG instance provided by the user via the SEARXNG_URL environment variable. Since it is not a plugin for SearXNG but a proxy, it maintains a clean separation, making it easier to upgrade or swap out search backends without impacting the AI client integration.

technical strengths and tradeoffs

mcp-searxng’s main technical strength is its clean implementation of the MCP protocol tailored for web search and content extraction, combined with its transport layer flexibility. The use of Node.js and TypeScript ensures a maintainable codebase with type safety and broad platform support.

Exposing two distinct tools—one for paginated search and one for URL content reading—addresses common AI assistant needs when interacting with web data. The caching mechanism in web_url_read is especially useful to reduce redundant network calls and speed up repeated queries, a practical consideration in real-world AI workflows.

Supporting both STDIO and HTTP transports is a valuable design choice. STDIO is simple and works well for local setups or direct CLI integrations, while HTTP mode opens the door for remote or containerized usage where TCP/IP communications are preferred. This dual transport support adds some complexity but pays off in deployment versatility.

One tradeoff is that mcp-searxng depends on a self-hosted SearXNG server running independently. This means users must manage and maintain their own SearXNG instance, which may not be trivial for everyone. However, this also offers full control over privacy and customization, which is critical for many users.

The codebase follows a minimal dependency philosophy and relies on standard JSON APIs, making it lightweight and easy to inspect or extend. The separation from SearXNG as a proxy rather than a plugin means no modifications are needed on the search engine side, simplifying updates.

quick start

The README provides clear commands and configurations to get mcp-searxng running. Here’s how to add it to your MCP client configuration, for example in 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 your actual SearXNG instance URL, like https://search.example.com.

Installation options include:

  • NPM global install:

    npm install -g mcp-searxng

    Then configure your MCP client to call mcp-searxng directly with the required environment variable.

  • Docker:

    Pull the pre-built image:

    docker pull isokoliuk/mcp-searxng:latest

    And configure your client to run the container with environment variables mapped.

    You can also build locally from the Dockerfile:

    docker build -t mcp-searxng:latest -f Dockerfile .

  • Docker Compose:

    Use the provided docker-compose.yml snippet to run the service, setting SEARXNG_URL in the environment.

Additionally, to enable HTTP transport mode instead of the default STDIO, set the MCP_HTTP_PORT environment variable:

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

This will make the MCP server listen on port 3000 for HTTP requests.

verdict

mcp-searxng is a solid, practical bridge for anyone wanting to add private, self-hosted web search to their MCP-compatible AI assistants. Its clear separation from SearXNG as a proxy keeps the architecture modular and avoids the complexity of plugin development. The support for paginated searches and advanced URL content extraction with caching meets real-world use cases for AI assistants querying the web.

The main limitation is the requirement to run and maintain a SearXNG instance, which may require some operational overhead. If you already have or can deploy SearXNG, mcp-searxng offers a straightforward, flexible way to extend your AI assistant’s capabilities without relying on commercial search APIs.

If you value privacy, control, and open-source tooling, and you’re comfortable with the MCP ecosystem, this project is definitely worth exploring. The code quality and transport flexibility make it adaptable to various deployment models, from local testing to containerized production.

Overall, mcp-searxng fills a niche in the growing MCP ecosystem by providing a reliable, open-source web search proxy that integrates cleanly with AI clients.

→ GitHub Repo: ihor-sokoliuk/mcp-searxng ⭐ 744 · TypeScript