Servidor MCP de SearxNG

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de búsqueda web mediante SearxNG, lo que permite a los asistentes de IA como Claude buscar en la web.

Creado por IA con supervisión humana, ¡porque a veces incluso la inteligencia artificial necesita que alguien le diga cuándo tomar un café! 🤖☕

Descripción general

Este proyecto implementa un servidor MCP que se conecta a SearxNG, un metabuscador que respeta la privacidad. El servidor proporciona una forma sencilla y eficiente para que los Modelos de Lenguaje Grandes (MLM) busquen en la web sin rastrear a los usuarios.

El servidor está diseñado específicamente para LLM e incluye únicamente las funciones esenciales para minimizar el uso de la ventana de contexto. Este enfoque optimizado garantiza una comunicación eficiente entre los LLM y el motor de búsqueda, preservando así un valioso espacio de contexto para información más importante.

Características

Búsqueda web centrada en la privacidad a través de SearxNG
API sencilla para la integración de LLM
Compatible con Claude Desktop y otros clientes compatibles con MCP
Parámetros de búsqueda configurables
Resultados de búsqueda limpios y formateados, optimizados para LLM

Integración con aplicaciones compatibles con MCP

Ejemplos de integración

Usando pipx run (Recomendado, no requiere instalación)

Crea un archivo .clauderc en tu directorio de inicio:

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

Usando uvx run (No requiere instalación)

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

Usando Python con pip (requiere instalación)

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

Uso con Docker (no requiere instalación)

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

Nota: Al utilizar Docker con servidores MCP:

Las variables de entorno deben pasarse directamente utilizando el indicador -e en la matriz args , ya que el objeto env no se pasa correctamente al contenedor Docker.
Si necesita acceder a una instancia de SearxNG que se ejecuta en localhost (p. ej., http://localhost:8080 ), debe usar el indicador --network=host para permitir que el contenedor acceda a la red del host. De lo contrario, "localhost" dentro del contenedor se referirá al contenedor en sí, no a su máquina host.
Al usar --network=host , las asignaciones de puertos ( -p ) no son necesarias y se ignorarán, ya que el contenedor comparte la pila de red del host directamente.

Configuración

Configurar el servidor usando variables de entorno:

Variable de entorno	Descripción	Valor predeterminado
BUSCAR_MCP_BUSCAR_URL	URL de la instancia de SearxNG a utilizar	https://paulgo.io/
TIEMPO DE ESPERA DE SEARXNG_MCP	Tiempo de espera de la solicitud HTTP en segundos	10
RECUENTO DE RESULTADOS PREDETERMINADO DE SEARXNG_MCP	Número predeterminado de resultados a devolver	10
SEARXNG_MCP_IDIOMA_PREDETERMINADO	Código de idioma para los resultados (por ejemplo, 'en', 'ru', 'all')	todo
FORMATO PREDETERMINADO DE SEARXNG_MCP	Formato predeterminado para los resultados ('texto', 'json')	texto
NIVEL DE REGISTRO DE SEARXNG_MCP	Nivel de registro (por ejemplo, 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRÍTICO')	ERROR
PROTOCOLO DE TRANSPORTE	Protocolo de transporte ('stdio' o 'sse')	estudio

Nota: Establecer niveles de registro superiores a ERROR (como DEBUG o INFO) puede interrumpir la integración con algunas aplicaciones debido a una salida excesiva en el canal de comunicación.

Puede encontrar una lista de instancias públicas de SearxNG en https://searx.space si no desea alojar la suya propia.

Instalación y uso

Prerrequisitos

Python 3.10 o superior
Una instancia de SearxNG (pública o autoalojada)

Opción 1: Ejecutar sin instalación (recomendado)

La forma más sencilla de utilizar este servidor es con pipx o uvx, lo que le permite ejecutar el paquete sin instalarlo permanentemente:

# Using pipx
pip install pipx  # Install pipx if you don't have it
pipx run searxng-simple-mcp

# OR using uvx
pip install uvx  # Install uvx if you don't have it
uvx run searxng-simple-mcp

Puede pasar opciones de configuración directamente:

# Using pipx with custom SearxNG instance
pipx run searxng-simple-mcp --searxng-url https://your-instance.example.com

Opción 2: Instalar desde PyPI o la fuente

Para una instalación más permanente:

# From PyPI using pip
pip install searxng-simple-mcp

# OR using uv (faster installation)
pip install uv
uv pip install searxng-simple-mcp

# OR from source
git clone https://github.com/Sacode/searxng-simple-mcp.git
cd searxng-simple-mcp
pip install uv
uv pip install -e .

Después de la instalación, puede ejecutar el servidor con:

# Run directly after installation
python -m searxng_simple_mcp.server

# OR with configuration options
python -m searxng_simple_mcp.server --searxng-url https://your-instance.example.com

Opción 3: Docker

Si prefieres usar Docker:

# Pull the Docker image
docker pull ghcr.io/sacode/searxng-simple-mcp:latest

# Run the container with default settings (stdio transport)
docker run --rm -i ghcr.io/sacode/searxng-simple-mcp:latest

# Run with environment file for configuration
docker run --rm -i --env-file .env ghcr.io/sacode/searxng-simple-mcp:latest

# Run with SSE transport (starts HTTP server on port 8000)
docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse ghcr.io/sacode/searxng-simple-mcp:latest

# Building locally
docker build -t searxng-simple-mcp:local .
docker run --rm -i searxng-simple-mcp:local

# Using Docker Compose
docker-compose up -d

Para obtener información completa sobre el uso de Docker, consulte la sección Configuración de Docker a continuación.

Protocolos de transporte

El servidor MCP admite dos protocolos de transporte:

STDIO (predeterminado): para aplicaciones CLI e integración directa
- Se utiliza de forma predeterminada en todos los ejemplos.
- Adecuado para la integración con Claude Desktop y otros clientes compatibles con MCP
- No se ha iniciado ningún servidor HTTP
SSE (Eventos enviados por el servidor): para clientes basados en web e integraciones basadas en HTTP
- Inicia un servidor HTTP al que los clientes pueden conectarse
- Útil para aplicaciones web y servicios que necesitan actualizaciones en tiempo real.
- Requiere mapeo de puertos al usar Docker

Uso del transporte SSE

Para utilizar el protocolo de transporte SSE:

Con ejecución directa :
# Set the transport protocol to SSE TRANSPORT_PROTOCOL=sse python -m searxng_simple_mcp.server # Or with FastMCP fastmcp run src/searxng_simple_mcp/server.py --transport sse
Con Docker :
# Run with SSE transport protocol docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse -e SEARXNG_MCP_SEARXNG_URL=https://your-instance.example.com ghcr.io/sacode/searxng-simple-mcp:latest
Con Docker Compose (desde el docker-compose.yml incluido):
environment: - SEARXNG_MCP_SEARXNG_URL=https://searx.info - SEARXNG_MCP_TIMEOUT=10 - SEARXNG_MCP_MAX_RESULTS=20 - SEARXNG_MCP_LANGUAGE=all - TRANSPORT_PROTOCOL=sse # Transport protocol: stdio or sse

Al utilizar SSE, el servidor será accesible a través de HTTP en http://localhost:8000 de manera predeterminada.

Para conectarse al servidor SSE desde un cliente MCP, utilice una configuración como:

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

Nota: No todas las aplicaciones admiten el protocolo de transporte SSE. Asegúrese de que su cliente MCP sea compatible con SSE antes de usar este método de transporte.

Desarrollo

Para desarrollo y pruebas:

# Install dependencies
uv pip install -e .

# Run linter and formatter
ruff check .
ruff check --fix .
ruff format .

# Run the server directly
python -m src.searxng_simple_mcp.server

# OR using FastMCP
fastmcp run src/searxng_simple_mcp/server.py  # Use stdio transport (default)
fastmcp run src/searxng_simple_mcp/server.py --transport sse  # Use sse transport

# Run in development mode (launches MCP Inspector)
fastmcp dev src/searxng_simple_mcp/server.py

Publicación en PyPI

Para los mantenedores que necesitan publicar nuevas versiones del paquete en PyPI:

# Install development dependencies
npm run install:deps

# Clean, build, and check the package
npm run build:package
npm run check:package

# Publish to PyPI (requires PyPI credentials)
npm run publish:pypi

# Alternatively, use the all-in-one commands to update version and publish
npm run publish:patch  # Increments patch version (1.0.1 -> 1.0.2)
npm run publish:minor  # Increments minor version (1.0.1 -> 1.1.0)
npm run publish:major  # Increments major version (1.0.1 -> 2.0.0)

Estos comandos harán lo siguiente:

Actualice la versión tanto en package.json como en pyproject.toml
Limpia el directorio dist para eliminar compilaciones antiguas
Construir el paquete (crear rueda y distribución de origen)
Comprueba si el paquete tiene errores
Subir el paquete a PyPI

Necesitará tener una cuenta de PyPI y estar autenticado con Twine. Puede configurar la autenticación mediante:

Creando un archivo .pypirc en su directorio de inicio
Uso de variables de entorno ( TWINE_USERNAME y TWINE_PASSWORD )
Uso de tokens de API de PyPI (recomendado)

Configuración de Docker

Al utilizar Docker con servidores MCP, tenga en cuenta estos puntos:

Integración con clientes MCP : utilice la configuración que se muestra en la sección Uso con Docker para la integración con Claude Desktop u otros clientes compatibles con MCP.
Protocolos de transporte :
- De forma predeterminada, el contenedor Docker utiliza el protocolo de transporte stdio
- Para el transporte SSE, consulte la sección Uso del transporte SSE
Opciones de configuración :
- Utilice un archivo de entorno (.env) para configurar el servidor: docker run --env-file .env ...
- Pase variables de entorno individuales con el indicador -e : docker run -e SEARXNG_MCP_SEARXNG_URL=https://example.com ...
- Consulte la sección Configuración para conocer las variables de entorno disponibles
Redes :
- Utilice --network=host cuando necesite acceder a servicios en su máquina host
- Utilice -p 8000:8000 al exponer el servidor SSE a su red

Estructura del paquete

searxng-simple-mcp/
├── src/
│   ├── run_server.py         # Entry point script
│   └── searxng_simple_mcp/   # Main package
├── docker-compose.yml        # Docker Compose configuration
├── Dockerfile                # Docker configuration
└── pyproject.toml            # Python project configuration

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

SearxNG MCP Server

Integrations