WebSearch-MCP

API de búsqueda web autoalojada

GitHub
41
Prueba este MCPPatrocinado

Documentación

WebSearch-MCP

smithery badge

Una implementación de servidor de Model Context Protocol (MCP) que proporciona capacidad de búsqueda web a través del transporte stdio. Este servidor se integra con una API de WebSearch Crawler para recuperar resultados de búsqueda.

Tabla de contenidos

Acerca de

WebSearch-MCP es un servidor de Model Context Protocol que proporciona capacidades de búsqueda web a asistentes de IA que admiten MCP. Permite que modelos de IA como Claude busquen en la web en tiempo real, recuperando información actualizada sobre cualquier tema.

El servidor se integra con un servicio de API Crawler que gestiona las búsquedas web reales y se comunica con los asistentes de IA mediante el protocolo estandarizado Model Context Protocol.

Instalación

Instalación mediante Smithery

Para instalar WebSearch para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @mnhlt/WebSearch-MCP --client claude

Instalación manual

npm install -g websearch-mcp

O úsalo sin instalarlo:

npx websearch-mcp

Configuración

El servidor MCP de WebSearch se puede configurar mediante variables de entorno:

  • API_URL: La URL de la API de WebSearch Crawler (por defecto: http://localhost:3001)
  • MAX_SEARCH_RESULT: Número máximo de resultados de búsqueda a devolver cuando no se especifica en la solicitud (por defecto: 5)

Ejemplos:

# Configure API URL
API_URL=https://crawler.example.com npx websearch-mcp

# Configure maximum search results
MAX_SEARCH_RESULT=10 npx websearch-mcp

# Configure both
API_URL=https://crawler.example.com MAX_SEARCH_RESULT=10 npx websearch-mcp

Configuración e Integración

La configuración de WebSearch-MCP consta de dos partes principales: configurar el servicio crawler que realiza las búsquedas web reales e integrar el servidor MCP con tus aplicaciones cliente de IA.

Configuración del Servicio Crawler

El servidor MCP de WebSearch requiere un servicio crawler para realizar las búsquedas web reales. Puedes configurar fácilmente el servicio crawler usando Docker Compose.

Requisitos previos

Inicio del Servicio Crawler

  1. Crea un archivo llamado docker-compose.yml con el siguiente contenido:
version: '3.8'

services:
  crawler:
    image: laituanmanh/websearch-crawler:latest
    container_name: websearch-api
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - LOG_LEVEL=info
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
    depends_on:
      - flaresolverr
    volumes:
      - crawler_storage:/app/storage

  flaresolverr:
    image: 21hsmw/flaresolverr:nodriver
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - TZ=UTC

volumes:
  crawler_storage:

workaround para Mac Apple Silicon

version: '3.8'

services:
  crawler:
    image: laituanmanh/websearch-crawler:latest
    container_name: websearch-api
    platform: "linux/amd64"
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - LOG_LEVEL=info
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
    depends_on:
      - flaresolverr
    volumes:
      - crawler_storage:/app/storage

  flaresolverr:
    image: 21hsmw/flaresolverr:nodriver
    platform: "linux/arm64"
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - TZ=UTC

volumes:
  crawler_storage:
  1. Inicia los servicios:
docker-compose up -d
  1. Verifica que los servicios estén en ejecución:
docker-compose ps
  1. Prueba el endpoint de salud de la API del crawler:
curl http://localhost:3001/health

Respuesta esperada:

{
  "status": "ok",
  "details": {
    "status": "ok",
    "flaresolverr": true,
    "google": true,
    "message": null
  }
}

La API del crawler estará disponible en http://localhost:3001.

Prueba de la API del Crawler

Puedes probar la API del crawler directamente con curl:

curl -X POST http://localhost:3001/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript best practices",
    "numResults": 2,
    "language": "en",
    "filters": {
      "excludeDomains": ["youtube.com"],
      "resultType": "all" 
    }
  }'

Configuración personalizada

Puedes personalizar el servicio crawler modificando las variables de entorno en el archivo docker-compose.yml:

  • PORT: El puerto en el que escucha la API del crawler (por defecto: 3001)
  • LOG_LEVEL: Nivel de registro (opciones: debug, info, warn, error)
  • FLARESOLVERR_URL: URL del servicio FlareSolverr (para evitar la protección de Cloudflare)

Integración con clientes MCP

Referencia rápida: Configuración de MCP

Aquí tienes una referencia rápida de la configuración de MCP para distintos clientes:

{
    "mcpServers": {
        "websearch": {
            "command": "npx",
            "args": [
                "websearch-mcp"
            ],
            "environment": {
                "API_URL": "http://localhost:3001",
                "MAX_SEARCH_RESULT": "5" // reduce to save your tokens, increase for wider information gain
            }
        }
    }
}

Solución alternativa para Windows, debido al Issue

{
	"mcpServers": {
	  "websearch": {
            "command": "cmd",
            "args": [
				"/c",
				"npx",
                "websearch-mcp"
            ],
            "environment": {
                "API_URL": "http://localhost:3001",
                "MAX_SEARCH_RESULT": "1"
            }
        }
	}
  }

Uso

Este paquete implementa un servidor MCP mediante transporte stdio que expone una herramienta web_search con los siguientes parámetros:

Parámetros

  • query (obligatorio): La consulta de búsqueda a realizar
  • numResults (opcional): Número de resultados a devolver (por defecto: 5)
  • language (opcional): Código de idioma para los resultados de búsqueda (p. ej., 'en')
  • region (opcional): Código de región para los resultados de búsqueda (p. ej., 'us')
  • excludeDomains (opcional): Dominios a excluir de los resultados
  • includeDomains (opcional): Incluir solo estos dominios en los resultados
  • excludeTerms (opcional): Términos a excluir de los resultados
  • resultType (opcional): Tipo de resultados a devolver ('all', 'news' o 'blogs')

Ejemplo de respuesta de búsqueda

Aquí hay un ejemplo de una respuesta de búsqueda:

{
  "query": "machine learning trends",
  "results": [
    {
      "title": "Top Machine Learning Trends in 2025",
      "snippet": "The key machine learning trends for 2025 include multimodal AI, generative models, and quantum machine learning applications in enterprise...",
      "url": "https://example.com/machine-learning-trends-2025",
      "siteName": "AI Research Today",
      "byline": "Dr. Jane Smith"
    },
    {
      "title": "The Evolution of Machine Learning: 2020-2025",
      "snippet": "Over the past five years, machine learning has evolved from primarily supervised learning approaches to more sophisticated self-supervised and reinforcement learning paradigms...",
      "url": "https://example.com/ml-evolution",
      "siteName": "Tech Insights",
      "byline": "John Doe"
    }
  ]
}

Pruebas locales

Para probar el servidor MCP de WebSearch localmente, puedes usar el cliente de prueba incluido:

npm run test-client

Esto iniciará el servidor MCP y una interfaz de línea de comandos simple que te permite ingresar consultas de búsqueda y ver los resultados.

También puedes configurar la API_URL para el cliente de prueba:

API_URL=https://crawler.example.com npm run test-client

Como librería

Puedes usar este paquete mediante programación:

import { createMCPClient } from '@modelcontextprotocol/sdk';

// Create an MCP client
const client = createMCPClient({
  transport: { type: 'subprocess', command: 'npx websearch-mcp' }
});

// Execute a web search
const response = await client.request({
  method: 'call_tool',
  params: {
    name: 'web_search',
    arguments: {
      query: 'your search query',
      numResults: 5,
      language: 'en'
    }
  }
});

console.log(response.result);

Solución de problemas

Problemas del servicio Crawler

  • API no accesible: Asegúrate de que el servicio crawler esté en ejecución y sea accesible en la API_URL configurada.
  • Resultados de búsqueda no disponibles: Revisa los registros del servicio crawler para ver si hay errores: 
    docker-compose logs crawler
  • Problemas con FlareSolverr: Algunos sitios web usan protección de Cloudflare. Si ves errores relacionados con esto, verifica si FlareSolverr está funcionando: 
    docker-compose logs flaresolverr

Problemas del servidor MCP

  • Errores de importación: Asegúrate de tener la última versión del SDK de MCP: 
    npm install -g @modelcontextprotocol/sdk@latest
  • Problemas de conexión: Asegúrate de que el transporte stdio esté configurado correctamente para tu cliente.

Desarrollo

Para trabajar en este proyecto:

  1. Clona el repositorio
  2. Instala las dependencias: npm install
  3. Compila el proyecto: npm run build
  4. Ejecuta en modo de desarrollo: npm run dev

El servidor espera una API de WebSearch Crawler como se define en el archivo swagger.json incluido. Asegúrate de que la API esté en ejecución en la API_URL configurada.

Estructura del proyecto

  • .gitignore: Especifica los archivos que Git debe ignorar (node_modules, dist, logs, etc.)
  • .npmignore: Especifica los archivos que no deben incluirse al publicar en npm
  • package.json: Metadatos del proyecto y dependencias
  • src/: Archivos fuente de TypeScript
  • dist/: Archivos JavaScript compilados (generados al compilar)

Publicación en npm

Para publicar este paquete en npm:

  1. Asegúrate de tener una cuenta de npm y haber iniciado sesión (npm login)
  2. Actualiza la versión en package.json (npm version patch|minor|major)
  3. Ejecuta npm publish

El archivo .npmignore garantiza que solo se incluyan los archivos necesarios en el paquete publicado:

  • El código compilado en dist/
  • Los archivos README.md y LICENSE
  • package.json

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Licencia

ISC