Labsco
The-AI-Workshops logo

SearXNG MCP Server

★ 23

from The-AI-Workshops

A privacy-respecting web search server for AI agents, powered by the SearXNG metasearch engine.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#database#devops#git#search#news

SearXNG MCP Server

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

Overview

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.

Integration with MCP Clients

SSE Configuration

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.

Python with Stdio Configuration

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"
      }
    }
  }
}

Docker with Stdio Configuration

{
  "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"
      }
    }
  }
}

Smithery with Stdio Configuration

If you installed the server using Smithery, you can configure your MCP client to run it via stdio. Smithery provides an exec command to run executables from within the tool's environment.

{
  "mcpServers": {
    "searxng": {
      "command": "smithery",
      "args": ["exec", "@The-AI-Workshops/searxng-mcp-server", "--", "python", "server.py"],
      // "cwd" (current working directory) might be automatically handled by Smithery.
      // If server.py is in a subdirectory, adjust the python script path e.g., "python", "path/to/server.py"
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768", // Adjust as needed
        "HOST": "0.0.0.0", // Typically not used by stdio server itself but good to set
        "PORT": "32769"  // Typically not used by stdio server itself
      }
    }
  }
}

Alternatively, you can find the path to the Python interpreter in the virtual environment created by Smithery (e.g., ~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python) and the path to server.py (e.g., ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server/server.py) and use those directly:

{
  "mcpServers": {
    "searxng": {
      "command": "~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python",
      "args": ["~/.smithery/tools/The-AI-Workshops/searxng-mcp-server/server.py"],
      // "cwd" should be the directory containing server.py if not using absolute paths for args,
      // or if server.py relies on relative paths for other files (like .env).
      // Example: "cwd": "~/.smithery/tools/The-AI-Workshops/searxng-mcp-server",
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768"
        // Other necessary env vars from .env can be duplicated here
      }
    }
  }
}

Ensure the paths are correct for your Smithery installation and that the .env file is discoverable by server.py (usually by setting cwd to the server's root directory or ensuring server.py loads it from an absolute path if Smithery sets one).

Building Your Own Server

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()

SearXNG Search Tool Parameters

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.