Web Search MCP

Extrai resultados de pesquisa do Google usando um navegador headless. Requer que o Chrome esteja instalado.

GitHub
16
Experimente este MCPPatrocinado

Documentação

Web Search MCP

Ask DeepWiki

Um servidor Model Context Protocol (MCP) que fornece funcionalidade de busca na web ao extrair resultados de pesquisa do Google, DuckDuckGo e Bing por meio de um navegador headless.

Install MCP Server

Recursos

  • Busca Multi-Mecanismo: Pesquisa no Google, DuckDuckGo e Bing com fallback automático quando um mecanismo é bloqueado ou não retorna nada
  • Resultados Estruturados: Títulos, URLs, domínios, trechos e classificações — com URLs de redirecionamento desembrulhadas para seus destinos reais
  • Conteúdo de Páginas Web: Busca e extrai conteúdo de texto de qualquer página web
  • Backends de Navegador Plugáveis: Selenium + Chrome headless (padrão) ou o navegador headless leve Obscura, selecionado por meio de uma variável de ambiente
  • Compatível com MCP: Totalmente compatível com Claude Desktop e outros clientes MCP

Ferramentas Disponíveis

search_web

Pesquisa na web em vários mecanismos (Google → DuckDuckGo → Bing) com fallback automático e retorna resultados estruturados.

Parâmetros:

  • query (string): A string de consulta de pesquisa
  • max_results (int, opcional): Número máximo de resultados a retornar (padrão: 10, máximo: 100)
  • include_snippets (bool, opcional): Se deve incluir trechos de texto (padrão: true)

Retorna:

  • Lista de resultados de pesquisa com:
    • title: Título da página
    • url: URL completa (wrappers de redirecionamento resolvidos para o destino real)
    • domain: Nome do domínio
    • snippet: Trecho de texto (se habilitado)
    • rank: Classificação do resultado de pesquisa
    • source_engine: Qual mecanismo produziu o resultado (google, duckduckgo ou bing)

get_webpage_content

Busca e retorna o conteúdo de texto de uma página web.

Parâmetros:

  • url (string): A URL da página web a ser buscada
  • max_length (int, opcional): Comprimento máximo do conteúdo (padrão: 5000, máximo: 20000)

Retorna:

  • Dicionário com:
    • url: A URL solicitada
    • title: Título da página
    • content: Conteúdo de texto extraído
    • length: Comprimento do conteúdo em caracteres

get_search_engine_status

Informa o backend de navegador ativo e a disponibilidade de cada mecanismo de pesquisa.

Retorna:

  • Dicionário com uma chave backend (selenium ou obscura) além de cada nome de mecanismo mapeado para available ou blocked.

reset_search_engines

Limpa a lista de mecanismos marcados como bloqueados durante a sessão (útil se um mecanismo se recuperar).

Retorna:

  • Uma mensagem de status em string.

Instalação

  1. Instale as dependências:

    # Using uv (recommended)
uv sync

# Or using pip
pip install -e .

  2. Instale um backend de navegador (escolha um):

    • Selenium (padrão) — requer Chrome:

      • No macOS: brew install --cask google-chrome
      • No Ubuntu: sudo apt-get install google-chrome-stable
      • No Windows: Baixe do site do Google Chrome

      O ChromeDriver é baixado e gerenciado automaticamente pelo webdriver-manager.

    • Obscura — não requer Chrome. Veja a seção Backends de Navegador abaixo.

Uso

Executando o Servidor MCP

# Run directly
python main.py

# Or using the installed script
web-search-mcp

O servidor iniciará e aguardará conexões MCP.

Usando com Claude Desktop

Adicione esta configuração às configurações MCP do seu Claude Desktop:

{
  "mcpServers": {
    "web-search-mcp": {
      "command": "uvx",
      "args": ["git+https://github.com/pranavms13/web-search-mcp"]
    }
  }
}

Exemplo de Uso no Claude

Uma vez conectado, você pode usar as ferramentas assim:

Search for "python web scraping tutorials" and show me the top 5 results.

Get the content from this webpage: https://example.com/article

Configuração

O buscador web usa estas opções de Chrome por padrão:

  • Modo headless (sem janela de navegador visível)
  • Tamanho da janela: 1920x1080
  • User agent: Navegador Chrome moderno
  • Flags de segurança para execução em contêineres

Backends de Navegador

O servidor pode renderizar páginas com um de dois backends intercambiáveis, selecionados por meio da variável de ambiente BROWSER_BACKEND:

BackendValorNotas
Seleniumselenium (padrão)Chrome headless via Selenium + webdriver-manager.
ObscuraobscuraNavegador headless Obscura via sua CLI. Leve, furtivo, sem necessidade de Chrome.

Ambos os backends produzem HTML totalmente renderizado por JS, que é então analisado com BeautifulSoup, portanto os resultados de pesquisa são idênticos em forma, independentemente do backend.

Usando Obscura

  1. Instale o binário do Obscura (veja seus releases), por exemplo no macOS:

    curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-macos.tar.gz
tar xzf obscura-x86_64-macos.tar.gz

  2. Execute o servidor com Obscura selecionado:

    BROWSER_BACKEND=obscura web-search-mcp

Se obscura não estiver no seu PATH, aponte para ele explicitamente com OBSCURA_BIN=/full/path/to/obscura. Quando o binário não puder ser encontrado, o servidor registra um aviso e volta automaticamente para o backend Selenium.

O backend ativo é informado pela ferramenta get_search_engine_status sob a chave backend.

Tratamento de Erros

A ferramenta inclui tratamento abrangente de erros para:

  • Timeouts de rede
  • Falhas do WebDriver
  • Erros de análise de página
  • URLs inválidas

Erros são registrados e fallbacks suaves são fornecidos.

Requisitos

  • Python 3.10+
  • Um backend de navegador: Chrome (Selenium) ou o binário Obscura
  • Conexão com a internet

Dependências

  • fastmcp: Framework do servidor MCP
  • selenium: Automação de navegador web (backend Selenium)
  • beautifulsoup4: Análise de HTML
  • webdriver-manager: Gerenciamento do driver do Chrome (backend Selenium)
  • lxml: Parser XML/HTML

O backend Obscura não tem dependência Python — ele é invocado como um binário CLI externo.

Limitações

  • Mecanismos de pesquisa podem limitar a taxa ou bloquear acesso automatizado; o fallback multi-mecanismo mitiga, mas não elimina isso
  • O Google em particular frequentemente bloqueia tráfego headless não furtivo — DuckDuckGo e Bing normalmente permanecem disponíveis como fallbacks
  • Os resultados podem variar com base na localização e na classificação de cada mecanismo
  • O backend Selenium requer Chrome; o backend Obscura requer o binário Obscura

Desenvolvimento

Para modificar ou estender a funcionalidade:

  1. Clone o repositório
  2. Instale em modo de desenvolvimento: uv sync ou pip install -e .
  3. Faça suas alterações
  4. Execute a suíte de testes: uv run pytest test.py -q
  5. Faça um teste rápido no servidor: python main.py (ou BROWSER_BACKEND=obscura OBSCURA_BIN=/path/to/obscura python main.py)

Licença

Este projeto é licenciado sob a Licença MIT. Você pode conferir em - LICENSE

Contribuindo

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