Búsqueda web-MCP

Una implementación de servidor de Protocolo de Contexto de Modelo (MCP) que proporciona funciones de búsqueda web mediante el transporte stdio. Este servidor se integra con una API de WebSearch Crawler para obtener resultados de búsqueda.

Tabla de contenido

Acerca de
Instalación
Configuración
Configuración e integración
- Configuración del servicio de rastreo
- Integración con clientes MCP
Uso
Solución de problemas
- Problemas con el servicio de rastreo
- Problemas con el servidor MCP
Desarrollo
- Estructura del proyecto
- Publicación en npm
Contribuyendo
Licencia

Acerca de

WebSearch-MCP es un servidor de Protocolo de Contexto de Modelo que proporciona funciones de búsqueda web a asistentes de IA compatibles con MCP. Permite a modelos de IA como Claude buscar en la web en tiempo real y obtener información actualizada sobre cualquier tema.

El servidor se integra con un servicio API de Crawler que maneja las búsquedas web reales y se comunica con los asistentes de IA mediante el Protocolo de contexto de modelo estandarizado.

Instalación

Instalación mediante herrería

Para instalar WebSearch para Claude Desktop automáticamente a través de Smithery :

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

Instalación manual

npm install -g websearch-mcp

O utilizar sin instalar:

npx websearch-mcp

Configuración

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

API_URL : La URL de la API del rastreador de búsqueda web (predeterminado: http://localhost:3001 )
MAX_SEARCH_RESULT : Número máximo de resultados de búsqueda a devolver cuando no se especifica en la solicitud (valor predeterminado: 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 implica dos partes principales: configurar el servicio de rastreo que realiza las búsquedas web reales e integrar el servidor MCP con sus aplicaciones cliente de IA.

Configuración del servicio de rastreo

El servidor MCP de WebSearch requiere un servicio de rastreo para realizar las búsquedas web. Puede configurarlo fácilmente con Docker Compose.

Prerrequisitos

Docker y Docker Compose

Iniciar el servicio de rastreo

Cree 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:

solución alternativa 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:

Iniciar los servicios:

docker-compose up -d

Verifique que los servicios se estén ejecutando:

docker-compose ps

Pruebe el punto final de estado de la API del rastreador:

curl http://localhost:3001/health

Respuesta esperada:

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

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

Prueba de la API del rastreador

Puedes probar la API del rastreador directamente usando 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

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

PORT : El puerto en el que escucha la API del rastreador (predeterminado: 3001)
LOG_LEVEL : Nivel de registro (opciones: depuración, información, advertencia, error)
FLARESOLVERR_URL : URL del servicio FlareSolverr (para omitir la protección de Cloudflare)

Integración con clientes MCP

Referencia rápida: Configuración de MCP

A continuación se muestra una referencia rápida para la configuración de MCP en diferentes 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 a un problema

{
	"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 que utiliza transporte stdio que expone una herramienta web_search con los siguientes parámetros:

Parámetros

query (obligatoria): La consulta de búsqueda a buscar
numResults (opcional): Número de resultados a devolver (predeterminado: 5)
language (opcional): código de idioma para los resultados de búsqueda (por ejemplo, 'en')
region (opcional): código de región para los resultados de búsqueda (por ejemplo, 'nosotros')
excludeDomains (opcional): Dominios que se excluirán de los resultados
includeDomains (opcional): solo incluye estos dominios en los resultados
excludeTerms (opcional): Términos que se excluirán de los resultados
resultType (opcional): tipo de resultados a devolver ('todos', 'noticias' o 'blogs')

Ejemplo de respuesta de búsqueda

A continuación se muestra 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 WebSearch MCP localmente, puede utilizar el cliente de prueba incluido:

npm run test-client

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

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

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

Como biblioteca

Puedes utilizar este paquete programáticamente:

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 con el servicio de rastreo

API inaccesible : asegúrese de que el servicio de rastreo esté en ejecución y sea accesible en la API_URL configurada.
Resultados de la búsqueda no disponibles : Verifique los registros del servicio de rastreo para ver si hay algún error:
docker-compose logs crawler
Problemas con FlareSolverr : Algunos sitios web usan la protección de Cloudflare. Si detecta errores relacionados, compruebe si FlareSolverr funciona correctamente.
docker-compose logs flaresolverr

Problemas con el servidor MCP

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

Desarrollo

Para trabajar en este proyecto:

Clonar el repositorio
Instalar dependencias: npm install
Construya el proyecto: npm run build
Ejecutar en modo de desarrollo: npm run dev

El servidor espera una API de WebSearch Crawler, tal como se define en el archivo swagger.json incluido. Asegúrese de que la API se esté ejecutando en la API_URL configurada.

Estructura del proyecto

.gitignore : especifica los archivos que Git debe ignorar (node_modules, dist, registros, etc.)
.npmignore : especifica los archivos que no deben incluirse al publicar en npm
package.json : metadatos y dependencias del proyecto
src/ : Archivos fuente de TypeScript
dist/ : Archivos JavaScript compilados (generados durante la compilación)

Publicación en npm

Para publicar este paquete en npm:

Asegúrese de tener una cuenta npm y de haber iniciado sesión ( npm login )
Actualice la versión en package.json ( npm version patch|minor|major )
Ejecutar npm publish

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

El código compilado en dist/
Archivos README.md y LICENSE
paquete.json

Contribuyendo

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

Licencia

ISC

WebSearch-MCP

Integrations