SearXNG MCP Server

Un servidor de búsqueda web que respeta la privacidad para agentes de IA, impulsado por el metabuscador SearXNG.

Documentación

Servidor MCP SearXNG

Una implementación MCP sse del servidor del Protocolo de Contexto de Modelo (MCP) integrado con SearXNG para proporcionar a los agentes de IA potentes capacidades de búsqueda que respetan la privacidad.

Descripción general

Este proyecto demuestra cómo construir un servidor MCP que permite a los agentes de IA realizar búsquedas web utilizando una instancia de SearXNG. Sirve como una plantilla práctica para crear tus propios servidores MCP, utilizando SearXNG como backend.

La implementación sigue las mejores prácticas establecidas por Anthropic para construir servidores MCP, permitiendo una integración perfecta con cualquier cliente compatible con MCP.

Requisitos previos

Python 3.9+
Acceso a una instancia de SearXNG en ejecución (local o remota)
Docker (opcional, para implementación en contenedores)
uv (opcional, para gestión rápida de dependencias de Python)
Smithery (opcional, para gestión de servidores MCP)

Servidor SearXNG (Requerido)

Debes tener un servidor SearXNG en ejecución y accesible. La forma recomendada es mediante 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

Esto ejecutará SearXNG en el puerto 32768 y persistirá la configuración en /root/searxng.
El servidor MCP espera que SearXNG esté disponible en http://172.17.0.1:32768 por defecto (ver .env).

Instalación

Usando uv

Instala uv si no lo tienes:

pip install uv

Clona este repositorio:

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

Instala las dependencias:

uv pip install -r requirements.txt

Crea un archivo .env basado en el ejemplo proporcionado:

nano .env
# Edit .env as needed

Configura tus variables de entorno en el archivo .env (ver sección de Configuración).

Usando Docker (Recomendado)

Construye la imagen Docker:

docker build -t mcp/searxng-mcp .

Crea un archivo .env y configura tus variables de entorno.

Ejecuta la imagen Docker:

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

Usando Smithery

Smithery es una herramienta de línea de comandos para gestionar herramientas de agentes de IA y servidores MCP.

Instala Smithery si no lo tienes (consulta la documentación de Smithery para varios métodos de instalación, por ejemplo, usando pipx):

pipx install smithery

Instala el servidor MCP SearXNG usando Smithery:

smithery install @The-AI-Workshops/searxng-mcp-server

Esto instalará el servidor y sus dependencias en un entorno dedicado gestionado por Smithery.

Después de la instalación, Smithery te proporcionará la ruta al servidor instalado. Deberás navegar a este directorio para configurarlo. Por ejemplo, si Smithery instala herramientas en ~/.smithery/tools/, la ruta podría ser ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server.

Crea un archivo .env en el directorio del servidor copiando el ejemplo:

# Example:
# cd ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server
cp .env.example .env
nano .env
# Edit .env as needed

Configura tus variables de entorno en el archivo .env (ver sección de Configuración).

Configuración

Las siguientes variables de entorno se pueden configurar en tu archivo .env:

Variable	Descripción	Ejemplo
SEARXNG_BASE_URL	URL base de tu instancia de SearXNG	http://172.17.0.1:32768
HOST	Host al que vincular al usar transporte SSE	0.0.0.0
PORT	Puerto para escuchar al usar transporte SSE	32769
TRANSPORT	Protocolo de transporte (sse o stdio)	sse

Ejecutando el Servidor

Usando uv

Transporte SSE

Establece TRANSPORT=sse en .env y luego:

uv run dev/searXNG-mcp/server.py

Transporte Stdio

Con stdio, el propio cliente MCP puede iniciar el servidor MCP, por lo que no hay nada que ejecutar en este punto.

Usando Docker

Transporte SSE

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

El montaje -v $(pwd)/dev/searXNG-mcp:/app te permite editar en vivo el código y el archivo .env en tu host y tener los cambios reflejados en el contenedor en ejecución.
El servidor estará disponible en http://localhost:32769/sse.

Transporte Stdio

Con stdio, el propio cliente MCP puede iniciar el contenedor del servidor MCP, por lo que no hay nada que ejecutar en este punto.

Ejecutando con Smithery

Transporte SSE

Establece TRANSPORT=sse en .env en el directorio del servidor instalado por Smithery. Luego, normalmente puedes ejecutar el servidor usando el intérprete de Python del entorno virtual que Smithery creó para la herramienta:

# Navigate to the server directory, e.g.,
# cd ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server
~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python server.py

Alternativamente, si Smithery proporciona un comando de ejecución directa para herramientas instaladas (consulta la documentación de Smithery):

smithery run @The-AI-Workshops/searxng-mcp-server

El servidor estará disponible según tu configuración de HOST y PORT en .env (por ejemplo, http://localhost:32769/sse).

Transporte Stdio

Con stdio, el propio cliente MCP iniciará el servidor. La configuración del cliente deberá apuntar al script server.py dentro del directorio gestionado por Smithery, potencialmente usando smithery exec o la ruta directa al intérprete de Python en el entorno virtual de la herramienta. Consulta la sección "Integración con Clientes MCP" para ejemplos.

Integración con Clientes MCP

Configuración SSE

Una vez que tengas el servidor ejecutándose con transporte SSE, puedes conectarte a él usando esta configuración:

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

Nota para usuarios de Windsurf: Usa serverUrl en lugar de url en tu configuración:

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

Nota para usuarios de n8n: Usa host.docker.internal en lugar de localhost ya que n8n tiene que alcanzar fuera de su propio contenedor hacia la máquina host:

Entonces la URL completa en el nodo MCP sería: http://host.docker.internal:32769/sse

Asegúrate de actualizar el puerto si estás usando un valor diferente al predeterminado 32769.

Python con Configuración Stdio

Agrega este servidor a tu configuración MCP para Claude Desktop, Windsurf o cualquier otro cliente MCP:

{
  "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 con Configuración Stdio

{
  "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 con Configuración Stdio

Si instalaste el servidor usando Smithery, puedes configurar tu cliente MCP para ejecutarlo vía stdio. Smithery proporciona un comando exec para ejecutar ejecutables desde el entorno de la herramienta.

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

Alternativamente, puedes encontrar la ruta al intérprete de Python en el entorno virtual creado por Smithery (por ejemplo, ~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python) y la ruta a server.py (por ejemplo, ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server/server.py) y usarlos directamente:

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

Asegúrate de que las rutas sean correctas para tu instalación de Smithery y que el archivo .env sea detectable por server.py (generalmente estableciendo cwd al directorio raíz del servidor o asegurando que server.py lo cargue desde una ruta absoluta si Smithery establece una).

Construyendo Tu Propio Servidor

Esta plantilla proporciona una base para construir servidores MCP más complejos. Para construir el tuyo propio:

Agrega tus propias herramientas creando métodos con el decorador @mcp.tool()
Crea tu propia función de ciclo de vida para agregar tus propias dependencias (clientes, conexiones de base de datos, etc.)
Agrega también prompts y recursos con @mcp.resource() y @mcp.prompt()

Parámetros de la Herramienta de Búsqueda SearXNG

La herramienta search admite los siguientes parámetros (todos opcionales excepto q):

q (requerido): La cadena de consulta de búsqueda.
categories: Lista separada por comas de categorías de búsqueda activas.
engines: Lista separada por comas de motores de búsqueda activos.
language: Código del idioma.
page: Número de página de búsqueda (predeterminado: 1).
time_range: [día, mes, año]
format: [json, csv, rss] (predeterminado: 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: Lista de plugins habilitados.
disabled_plugins: Lista de plugins deshabilitados.
enabled_engines: Lista de motores habilitados.
disabled_engines: Lista de motores deshabilitados.

Consulta la documentación de SearXNG para más detalles.

Licencia

Licencia MIT