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

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:

1. 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.

2. 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.

3. 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:

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:

1. 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

2. 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

3. 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:

1. Actualice la versión tanto en package.json como en pyproject.toml

2. Limpia el directorio dist para eliminar compilaciones antiguas

3. Construir el paquete (crear rueda y distribución de origen)

4. Comprueba si el paquete tiene errores

5. 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:

1. 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.

2. 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

3. 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

4. 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.