MCP Web Search Tool

Um servidor para pesquisa web em tempo real usando provedores conectáveis, alimentado pela Brave Search API.

Documentação

MCP Web Search Tool

Um servidor MCP que oferece ao assistente busca web ao vivo, leitura de páginas completas e citações de fontes. Transporte Stdio, provedores plugáveis, sem dependências de scraper.

Início rápido · Ferramentas · Configuração · Clientes · Segurança · Changelog

Visão geral

Cinco ferramentas: web_search, news_search, image_search, fetch_url, list_providers. A busca retorna resumos classificados com ids estáveis; fetch_url lê a página por trás de qualquer id. Brave Search é o provedor principal; DuckDuckGo funciona sem chave como alternativa.

Requisitos


Node.js	`>= 20.18` (usa `fetch` nativo)
npm	`>= 10`
Chave da API Brave Search	opcional. Sem ela, DuckDuckGo lida com `web_search`. `news_search` e `image_search` exigem uma chave.

Início rápido

git clone https://github.com/gabrimatic/mcp-web-search-tool.git
cd mcp-web-search-tool
npm install
cp .env.example .env   # edit BRAVE_API_KEY if you have one
npm run build
npm start

Execute com Docker:

docker build -t mcp-web-search .
docker run --rm -i -e BRAVE_API_KEY mcp-web-search

Para integração com Claude Desktop, Claude Code, Codex, VS Code, Cursor ou Windsurf, consulte MCP_CLIENTS.md.

Ferramentas

Cada ferramenta retorna dois blocos de conteúdo: uma renderização em Markdown para o modelo e um bloco JSON cercado com o payload estruturado. Erros retornam como conteúdo isError: true com uma mensagem acionável; apenas chamadas de ferramentas desconhecidas geram erro de protocolo.

`web_search`

Busca web ao vivo. Use primeiro para respostas atuais com respaldo de fontes.

Parâmetro	Tipo	Descrição
`search_term`	string, obrigatório	String de consulta.
`provider`	enum	`"brave search"` ou `"duckduckgo"`. Padrão: Brave quando uma chave está definida; caso contrário, DuckDuckGo.
`count`	int (1–20)	Número de resultados. Padrão: 10.
`offset`	int	Deslocamento de paginação (somente web).
`cursor`	string	Cursor opaco de uma resposta anterior.
`freshness`	string	`pd` (24h), `pw` (semana), `pm` (mês), `py` (ano) ou `YYYY-MM-DDtoYYYY-MM-DD`.
`country`	string	Código de país ISO.
`search_lang`	string	Idioma da interface, ex.: `en`.
`safesearch`	enum	`off`, `moderate`, `strict`.
`include_domains`	string[]	Restringe resultados a esses hosts.
`exclude_domains`	string[]	Remove resultados desses hosts (correspondência por sufixo de hostname).

`news_search`

Notícias recentes com nome da fonte e data de publicação. Somente Brave.

`image_search`

Resultados de imagens com miniaturas. Somente Brave.

`fetch_url`

Lê um resultado de busca ou qualquer URL http(s). Passe um id de resultado de uma busca anterior (preferido) ou uma URL completa.

Parâmetro	Tipo	Descrição
`id_or_url`	string	Um id de resultado (ex.: `r_a1b2c3d4e5f6`) ou uma URL `http(s)` completa.
`url`	string	Alias obsoleto para `id_or_url`.
`max_chars`	int (200–200 000)	Limite suave de caracteres retornados. Padrão: 8000.
`cursor`	string	Cursor de uma resposta anterior para continuar a leitura.

Retorna o título da página, texto legível (scripts, estilos, navegação, rodapé e aside removidos), os primeiros 25 links externos, status HTTP, tipo de conteúdo, tamanho em bytes e um nextCursor quando truncado.

Recusa esquemas não-http(s) e qualquer host que resolva para endereço privado, loopback, link-local, multicast ou IPv4-mapeado para IPv6 privado. Detalhes: SECURITY.md.

`list_providers`

Retorna os provedores registrados e o padrão atual. Chame uma vez se não tiver certeza se news_search ou image_search estão disponíveis nesta sessão.

Configuração

Toda a configuração é orientada por ambiente. Referência: .env.example.

Variável	Padrão	Finalidade
`BRAVE_API_KEY`	vazio	Chave da API Brave Search. Quando não definida, DuckDuckGo é usado.
`MAX_RESULTS`	`10`	Contagem padrão de resultados (limitada a 1–50).
`REQUEST_TIMEOUT`	`10000`	Tempo limite por solicitação em ms (1 000–60 000).
`DEFAULT_PROVIDER`	auto	Força um provedor específico (ex.: `duckduckgo`).
`ALLOW_KEYLESS`	`true`	Quando `false`, o servidor recusa iniciar sem `BRAVE_API_KEY`.
`CACHE_MAX_ENTRIES` / `CACHE_TTL_MS`	`256` / `300000`	Cache de busca.
`FETCH_CACHE_MAX` / `FETCH_CACHE_TTL_MS`	`128` / `600000`	Cache de busca de URL.
`FETCH_TIMEOUT_MS` / `FETCH_MAX_BYTES`	`15000` / `2000000`	Orçamento por solicitação para `fetch_url`.

Estrutura do projeto

src/
├── index.ts                    MCP server: tool registry, dispatch, rendering
├── config.ts                   env loader, validation, defaults
├── providers/
│   ├── SearchProvider.ts       abstract contract and shared types
│   ├── SearchProviderFactory   registry and default selection
│   ├── BraveSearchProvider     web/news/images via Brave API
│   └── DuckDuckGoProvider      keyless HTML-lite fallback
├── services/
│   ├── SearchService.ts        provider dispatch, LRU+TTL cache
│   └── FetchService.ts         safe URL fetch, readable extraction
└── utils/
    ├── http.ts                 native fetch, retry/backoff/timeout
    ├── html.ts                 zero-dep HTML to text + links
    ├── cache.ts                LRU+TTL cache
    └── ids.ts                  stable result-id minting and resolution
tests/                          vitest suite

Adicionar um provedor

import { SearchProvider, SearchResponse, SearchOptions } from './SearchProvider.js';

export class MyProvider extends SearchProvider {
  getName() { return 'My Provider'; }
  override requiresApiKey() { return true; }
  async search(query: string, _opts: SearchOptions = {}): Promise<SearchResponse> {
    const out = this.emptyResponse(query, 'web');
    out.results = mapped; // shape: SearchResult[]
    return out;
  }
}

Registre-o em SearchProviderFactory.setupDefaults. Ids de resultado são gerados automaticamente quando você chama mintResultId(url) em cada entrada.

Desenvolvimento

npm run dev          # tsx watch mode
npm test             # vitest (23 tests)
npm run lint
npm run format
npm run build

CI roda em Node 20, 22 e 24, além de build de imagem Docker. Os testes cobrem o cache LRU+TTL, extrator de HTML, parser DuckDuckGo, cache do serviço de busca, retry/backoff HTTP, proteção SSRF, correspondência de domínio e o resolvedor de id de resultado.

Exemplos de prompts

"O que os analistas estão dizendo sobre a corrida pelo MVP após os jogos da NBA desta noite?"
"Resuma os três principais resultados para RAG benchmarks 2025 e extraia o resumo do primeiro artigo."
"Encontre imagens do campo profundo mais recente do telescópio Webb, depois abra a página da NASA e cite a legenda."
"Como está o clima em Berlim agora?"

Licença

Licença MIT

Desenvolvedor

Por Soroush Yousefpour

Vídeo no YouTube

Uma demonstração curta do MCP Web Search Tool com Claude:

Claude + MCP Web Search – Demonstração ao vivo

Artigo no Medium

Contexto sobre o projeto e como ele funciona:

Mergulho profundo no MCP Web Search Tool

MCP Web Search Tool

Documentação