SearxNG MCP Server

Proporciona capacidades de búsqueda web utilizando una instancia autoalojada de SearxNG, permitiendo a los asistentes de IA buscar en la web.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de SearxNG

Un servidor de Model Context Protocol (MCP) que proporciona capacidades de búsqueda web mediante SearxNG, permitiendo que asistentes de IA como Claude busquen en la web.

Creado por IA con supervisión humana: porque incluso la inteligencia artificial a veces necesita que alguien le diga cuándo tomarse un descanso para tomar 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 de Gran Tamaño busquen en la web sin rastrear a los usuarios.

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

Características

Búsqueda web centrada en la privacidad mediante SearxNG
API sencilla para la integración con LLMs
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 LLMs

Integración con aplicaciones compatibles con MCP

Ejemplos de integración

Usando pipx run (Recomendado, sin necesidad de instalación)

Cree un archivo .clauderc en su 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 (Sin necesidad de 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"
      }
    }
  }
}

Usando con Docker (Sin necesidad de 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 usar Docker con servidores MCP:

Las variables de entorno deben pasarse directamente usando la bandera -e en el arreglo 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 (por ejemplo, http://localhost:8080), debe usar la bandera --network=host para permitir que el contenedor acceda a la red del host. De lo contrario, "localhost" dentro del contenedor se referirá al propio contenedor, no a su máquina host.
Al usar --network=host, los mapeos de puertos (-p) no son necesarios y se ignorarán, ya que el contenedor comparte directamente la pila de red del host.

Configuración

Configure el servidor usando variables de entorno:

Variable de entorno	Descripción	Valor predeterminado
SEARXNG_MCP_SEARXNG_URL	URL de la instancia de SearxNG a usar	https://paulgo.io/
SEARXNG_MCP_TIMEOUT	Tiempo de espera de solicitudes HTTP en segundos	10
SEARXNG_MCP_DEFAULT_RESULT_COUNT	Número predeterminado de resultados a devolver	10
SEARXNG_MCP_DEFAULT_LANGUAGE	Código de idioma para los resultados (por ejemplo, 'en', 'ru', 'all')	all
SEARXNG_MCP_DEFAULT_FORMAT	Formato predeterminado para los resultados ('text', 'json')	text
SEARXNG_MCP_LOG_LEVEL	Nivel de registro (por ejemplo, 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')	ERROR
TRANSPORT_PROTOCOL	Protocolo de transporte ('stdio' o 'sse')	stdio

Nota: Establecer niveles de registro superiores a ERROR (como DEBUG o INFO) puede romper la integración con algunas aplicaciones debido a la 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

Requisitos previos

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 usar este servidor es con pipx o uvx, 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 desde el código 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 prefiere 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 usa de forma predeterminada en todos los ejemplos
- Adecuado para la integración con Claude Desktop y otros clientes compatibles con MCP
- No se inicia 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 usar 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 usar SSE, el servidor será accesible a través de HTTP en http://localhost:8000 de forma predeterminada.

Para conectarse al servidor SSE desde un cliente MCP, use 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:

Actualizarán la versión tanto en package.json como en pyproject.toml
Limpiarán el directorio dist para eliminar compilaciones antiguas
Compilarán el paquete (creando wheel y distribución de código fuente)
Verificarán el paquete en busca de errores
Subirán el paquete a PyPI

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

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

Configuración de Docker

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

Integración con clientes MCP: Use la configuración que se muestra en la sección Usando con Docker para integrarse con Claude Desktop u otros clientes compatibles con MCP.
Protocolos de transporte:
- De forma predeterminada, el contenedor Docker usa el protocolo de transporte stdio
- Para el transporte SSE, consulte la sección Uso del transporte SSE
Opciones de configuración:
- Use un archivo de entorno (.env) para configurar el servidor: docker run --env-file .env ...
- Pase variables de entorno individuales con la bandera -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:
- Use --network=host cuando necesite acceder a servicios en su máquina host
- Use -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

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una Solicitud de extracción (Pull Request).

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.