WebSearch-MCP

API de Pesquisa Web auto-hospedada

GitHub
41
Experimente este MCPPatrocinado

Documentação

WebSearch-MCP

smithery badge

Uma implementação de servidor Model Context Protocol (MCP) que fornece capacidade de pesquisa na web via transporte stdio. Este servidor integra-se com uma API WebSearch Crawler para recuperar resultados de pesquisa.

Sumário

Sobre

WebSearch-MCP é um servidor Model Context Protocol que fornece capacidades de pesquisa na web para assistentes de IA que suportam MCP. Ele permite que modelos de IA como Claude pesquisem na web em tempo real, recuperando informações atualizadas sobre qualquer tópico.

O servidor integra-se com um serviço de API Crawler que realiza as pesquisas na web, e comunica-se com assistentes de IA usando o Model Context Protocol padronizado.

Instalação

Instalando via Smithery

Para instalar o WebSearch para Claude Desktop automaticamente via Smithery:

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

Instalação Manual

npm install -g websearch-mcp

Ou use sem instalar:

npx websearch-mcp

Configuração

O servidor MCP WebSearch pode ser configurado usando variáveis de ambiente:

  • API_URL: A URL da API WebSearch Crawler (padrão: http://localhost:3001)
  • MAX_SEARCH_RESULT: Número máximo de resultados de pesquisa a retornar quando não especificado na solicitação (padrão: 5)

Exemplos:

# 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

Configuração e Integração

A configuração do WebSearch-MCP envolve duas partes principais: configurar o serviço crawler que realiza as pesquisas na web, e integrar o servidor MCP com seus aplicativos clientes de IA.

Configurando o Serviço Crawler

O servidor MCP WebSearch requer um serviço crawler para realizar as pesquisas na web. Você pode configurar facilmente o serviço crawler usando Docker Compose.

Pré-requisitos

Iniciando o Serviço Crawler

  1. Crie um arquivo chamado docker-compose.yml com o seguinte conteúdo:
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:

solução 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:
  1. Inicie os serviços:
docker-compose up -d
  1. Verifique se os serviços estão em execução:
docker-compose ps
  1. Teste o endpoint de saúde da API do crawler:
curl http://localhost:3001/health

Resposta esperada:

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

A API do crawler estará disponível em http://localhost:3001.

Testando a API do Crawler

Você pode testar a API do crawler diretamente 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" 
    }
  }'

Configuração Personalizada

Você pode personalizar o serviço crawler modificando as variáveis de ambiente no arquivo docker-compose.yml:

  • PORT: A porta na qual a API do crawler escuta (padrão: 3001)
  • LOG_LEVEL: Nível de registro (opções: debug, info, warn, error)
  • FLARESOLVERR_URL: URL do serviço FlareSolverr (para contornar a proteção Cloudflare)

Integrando com Clientes MCP

Referência Rápida: Configuração MCP

Aqui está uma referência rápida para a configuração MCP em 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
            }
        }
    }
}

Solução alternativa para Windows, devido à Issue

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

Uso

Este pacote implementa um servidor MCP usando transporte stdio que expõe uma ferramenta web_search com os seguintes parâmetros:

Parâmetros

  • query (obrigatório): A consulta de pesquisa a ser realizada
  • numResults (opcional): Número de resultados a retornar (padrão: 5)
  • language (opcional): Código de idioma para resultados de pesquisa (ex.: 'en')
  • region (opcional): Código de região para resultados de pesquisa (ex.: 'us')
  • excludeDomains (opcional): Domínios a excluir dos resultados
  • includeDomains (opcional): Incluir apenas estes domínios nos resultados
  • excludeTerms (opcional): Termos a excluir dos resultados
  • resultType (opcional): Tipo de resultados a retornar ('all', 'news' ou 'blogs')

Exemplo de Resposta de Pesquisa

Aqui está um exemplo de resposta de pesquisa:

{
  "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"
    }
  ]
}

Testando Localmente

Para testar o servidor MCP WebSearch localmente, você pode usar o cliente de teste incluído:

npm run test-client

Isso iniciará o servidor MCP e uma interface de linha de comando simples que permite inserir consultas de pesquisa e ver os resultados.

Você também pode configurar a API_URL para o cliente de teste:

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

Como Biblioteca

Você pode usar este pacote programaticamente:

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);

Solução de Problemas

Problemas com o Serviço Crawler

  • API Inacessível: Certifique-se de que o serviço crawler está em execução e acessível na API_URL configurada.
  • Resultados de Pesquisa Indisponíveis: Verifique os logs do serviço crawler para ver se há erros: 
    docker-compose logs crawler
  • Problemas com FlareSolverr: Alguns sites usam proteção Cloudflare. Se você vir erros relacionados a isso, verifique se o FlareSolverr está funcionando: 
    docker-compose logs flaresolverr

Problemas com o Servidor MCP

  • Erros de Importação: Certifique-se de ter a versão mais recente do SDK MCP: 
    npm install -g @modelcontextprotocol/sdk@latest
  • Problemas de Conexão: Certifique-se de que o transporte stdio está configurado corretamente para seu cliente.

Desenvolvimento

Para trabalhar neste projeto:

  1. Clone o repositório
  2. Instale as dependências: npm install
  3. Compile o projeto: npm run build
  4. Execute em modo de desenvolvimento: npm run dev

O servidor espera uma API WebSearch Crawler conforme definido no arquivo swagger.json incluído. Certifique-se de que a API está em execução na API_URL configurada.

Estrutura do Projeto

  • .gitignore: Especifica arquivos que o Git deve ignorar (node_modules, dist, logs, etc.)
  • .npmignore: Especifica arquivos que não devem ser incluídos ao publicar no npm
  • package.json: Metadados do projeto e dependências
  • src/: Arquivos-fonte TypeScript
  • dist/: Arquivos JavaScript compilados (gerados ao compilar)

Publicando no npm

Para publicar este pacote no npm:

  1. Certifique-se de ter uma conta npm e estar conectado (npm login)
  2. Atualize a versão no package.json (npm version patch|minor|major)
  3. Execute npm publish

O arquivo .npmignore garante que apenas os arquivos necessários sejam incluídos no pacote publicado:

  • O código compilado em dist/
  • Arquivos README.md e LICENSE
  • package.json

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

ISC