SearxNG MCP Server

A Model Context Protocol (MCP) server that provides web search capabilities using SearxNG, allowing AI assistants like Claude to search the web.

> Created by AI with human supervision - because sometimes even artificial intelligence needs someone to tell it when to take a coffee break! 🤖☕

Overview

This project implements an MCP server that connects to SearxNG, a privacy-respecting metasearch engine. The server provides a simple and efficient way for Large Language Models to search the web without tracking users.

The server is specifically designed for LLMs and includes only essential features to minimize context window usage. This streamlined approach ensures efficient communication between LLMs and the search engine, preserving valuable context space for more important information.

Features

- Privacy-focused web search through SearxNG
- Simple API for LLM integration
- Compatible with Claude Desktop and other MCP-compliant clients
- Configurable search parameters
- Clean, formatted search results optimized for LLMs

Integration with MCP-Compatible Applications

Integration Examples

Using pipx run (Recommended, no installation required)

Create a .clauderc file in your home directory:

{
  "mcpServers": {
    "searxng": {
      "command": "pipx",
      "args": [
        "run", "searxng-simple-mcp@latest"
      ],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

Using uvx run (No installation required)

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": [
        "run", "searxng-simple-mcp@latest"
      ],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

Using Python with pip (requires installation)

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_simple_mcp.server"],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

Using with Docker (No installation required)

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "SEARXNG_MCP_SEARXNG_URL=http://localhost:8080",
        "ghcr.io/sacode/searxng-simple-mcp:latest"
      ]
    }
  }
}

Note: When using Docker with MCP servers:

1. Environment variables must be passed directly using the -e flag in the args array, as the env object is not properly passed to the Docker container.
2. If you need to access a SearxNG instance running on localhost (e.g., <http://localhost:8080>), you must use the --network=host flag to allow the container to access the host's network. Otherwise, "localhost" inside the container will refer to the container itself, not your host machine.
3. When using --network=host, port mappings (-p) are not needed and will be ignored, as the container shares the host's network stack directly.

Configuration

Configure the server using environment variables:

| Environment Variable | Description | Default Value |
|----------------------|-------------|---------------|
| SEARXNG_MCP_SEARXNG_URL | URL of the SearxNG instance to use | <https://paulgo.io/> |
| SEARXNG_MCP_TIMEOUT | HTTP request timeout in seconds | 10 |
| SEARXNG_MCP_DEFAULT_RESULT_COUNT | Default number of results to return | 10 |
| SEARXNG_MCP_DEFAULT_LANGUAGE | Language code for results (e.g., 'en', 'ru', 'all') | all |
| SEARXNG_MCP_DEFAULT_FORMAT | Default format for results ('text', 'json') | text |
| SEARXNG_MCP_LOG_LEVEL | Logging level (e.g., 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL') | ERROR |
| TRANSPORT_PROTOCOL | Transport protocol ('stdio' or 'sse') | stdio |

Note: Setting log levels higher than ERROR (such as DEBUG or INFO) may break integration with some applications due to excessive output in the communication channel.

You can find a list of public SearxNG instances at https://searx.space if you don't want to host your own.

Installation & Usage

Prerequisites

- Python 3.10 or higher
- A SearxNG instance (public or self-hosted)

Option 1: Run Without Installation (Recommended)

The easiest way to use this server is with pipx or uvx, which allows you to run the package without installing it permanently:

```bash