Servidor MCP de SearxNG

Name: SearxNG MCP Server
Author: Sacode

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

Related MCP server: MCP SearxNG Search

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