An MCP sse implementation of the Model Context Protocol (MCP) server integrated with SearXNG for providing AI agents with powerful, privacy-respecting search capabilities.

This project demonstrates how to build an MCP server that enables AI agents to perform web searches using a SearXNG instance. It serves as a practical template for creating your own MCP servers, using SearXNG as a backend.

The implementation follows the best practices laid out by Anthropic for building MCP servers, allowing seamless integration with any MCP-compatible client.

• Python 3.9+
• Access to a running SearXNG instance (local or remote)
• Docker (optional, for containerized deployment)
• uv (optional, for fast Python dependency management)

You must have a SearXNG server running and accessible. The recommended way is via Docker:

docker run -d --name=searxng -p 32768:8080 -v "/root/searxng:/etc/searxng" \
  -e "BASE_URL=http://0.0.0.0:32768/" \
  -e "INSTANCE_NAME=home" \
  --restart always searxng/searxng

• This will run SearXNG on port 32768 and persist configuration in /root/searxng.
• The MCP server expects SearXNG to be available at http://172.17.0.1:32768 by default (see .env).

Install uv if you don't have it:

pip install uv

Clone this repository:

git clone https://github.com/The-AI-Workshops/searxng-mcp-server.git
cd searxng-mcp-server/dev/searXNG-mcp

Install dependencies:

uv pip install -r requirements.txt

Create a .env file based on the provided example:

nano .env
# Edit .env as needed

Configure your environment variables in the .env file (see Configuration section).

Build the Docker image:

docker build -t mcp/searxng-mcp .

Create a .env file and configure your environment variables.

Run the Docker image:

docker run -d --env-file ./.env -p 32769:32769 mcp/searxng-mcp

The following environment variables can be configured in your .env file:

SSE Transport

Set TRANSPORT=sse in .env then:

uv run dev/searXNG-mcp/server.py

Stdio Transport

With stdio, the MCP client itself can spin up the MCP server, so nothing to run at this point.

SSE Transport

docker build -t mcp/searxng-mcp .
docker run --rm -it -p 32769:32769 --env-file dev/searXNG-mcp/.env -v $(pwd)/dev/searXNG-mcp:/app mcp/searxng-mcp

• The -v $(pwd)/dev/searXNG-mcp:/app mount allows you to live-edit the code and .env file on your host and have changes reflected in the running container.
• The server will be available at http://localhost:32769/sse.

Stdio Transport

With stdio, the MCP client itself can spin up the MCP server container, so nothing to run at this point.

Once you have the server running with SSE transport, you can connect to it using this configuration:

{
  "mcpServers": {
    "searxng": {
      "transport": "sse",
      "url": "http://localhost:32769/sse"
    }
  }
}

Note for Windsurf users: Use serverUrl instead of url in your configuration:

{
  "mcpServers": {
    "searxng": {
      "transport": "sse",
      "serverUrl": "http://localhost:32769/sse"
    }
  }
}

Note for n8n users: Use host.docker.internal instead of localhost since n8n has to reach outside of its own container to the host machine:

So the full URL in the MCP node would be: http://host.docker.internal:32769/sse

Make sure to update the port if you are using a value other than the default 32769.

Add this server to your MCP configuration for Claude Desktop, Windsurf, or any other MCP client:

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["dev/searXNG-mcp/server.py"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768",
        "HOST": "0.0.0.0",
        "PORT": "32769"
      }
    }
  }
}

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "TRANSPORT",
               "-e", "SEARXNG_BASE_URL",
               "-e", "HOST",
               "-e", "PORT",
               "mcp/searxng-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768",
        "HOST": "0.0.0.0",
        "PORT": "32769"
      }
    }
  }
}

This template provides a foundation for building more complex MCP servers. To build your own:

• Add your own tools by creating methods with the @mcp.tool() decorator
• Create your own lifespan function to add your own dependencies (clients, database connections, etc.)
• Add prompts and resources as well with @mcp.resource() and @mcp.prompt()

The search tool supports the following parameters (all optional except q):

• q (required): The search query string.
• categories: Comma-separated list of active search categories.
• engines: Comma-separated list of active search engines.
• language: Code of the language.
• page: Search page number (default: 1).
• time_range: [day, month, year]
• format: [json, csv, rss] (default: json)
• results_on_new_tab: [0, 1]
• image_proxy: [true, false]
• autocomplete: [google, dbpedia, duckduckgo, mwmbl, startpage, wikipedia, stract, swisscows, qwant]
• safesearch: [0, 1, 2]
• theme: [simple]
• enabled_plugins: List of enabled plugins.
• disabled_plugins: List of disabled plugins.
• enabled_engines: List of enabled engines.
• disabled_engines: List of disabled engines.

See the SearXNG documentation for more details.

MIT License