mcp-google-custom-search

Google Custom Search MCP

Português | Русский

A1 Google Custom Search MCP permite que um aplicativo de IA pesquise na web e em imagens em linguagem natural por meio do seu Mecanismo de Pesquisa Programável. Peça páginas, refine por idioma, país, data ou site, navegue pelos resultados e baixe arquivos de imagem com miniaturas.

Ele usa a API JSON do Google Custom Search com sua chave de API do Google Cloud. Você decide o que o mecanismo cobre — um punhado de sites ou a web inteira — e o servidor torna explícitos os limites da API JSON, em vez de sugerir que toda tarefa de pesquisa é possível.

• 3 ferramentas. Pesquisa na web, pesquisa de imagens e uma saída de escape GET bruta para parâmetros que as ferramentas tipadas não expõem.
• Somente leitura de ponta a ponta. A API JSON do Custom Search não tem endpoint de escrita; toda ferramenta é marcada como somente leitura e nada aqui pode modificar dados.
• Você controla a cobertura. A configuração do mecanismo decide o que é pesquisado; resultados e classificação podem diferir do google.com.
• A chave permanece em um cabeçalho. Autenticação por chave de API — sem OAuth, sem escopos; a chave viaja no cabeçalho X-Goog-Api-Key e nunca aparece em uma URL.
• Não é o Google Search Console. Não pode informar como seu próprio site é indexado ou classificado.

Comece com uma pergunta somente leitura:

Encontre artigos recentes sobre adoção de passkeys do último mês e resuma os três principais resultados.

Conecte o servidor · Explore casos de uso · Abra a documentação técnica

Veja funcionando em um minuto

Você: Encontre artigos recentes sobre adoção de passkeys, somente em inglês, do último mês.

Assistente: Executa uma pesquisa pelo seu mecanismo e mostra o título, link e trecho de cada resultado. Nada muda — toda ferramenta é somente leitura.

Você: Mostre a próxima página.

Assistente: Continua a partir do cursor next_start e mostra os resultados 11–20 da mesma consulta.

Você: Agora encontre fotos grandes de imprensa sobre o mesmo tópico.

Assistente: Alterna para pesquisa de imagens e retorna arquivos de imagem com dimensões, miniaturas e as páginas que os hospedam.

Conteúdo

• Início rápido
• O que você pode pedir
• Como uma pesquisa funciona
• O que pode mudar
• Obtendo acesso
• Configuração
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa de Node.js 20+, uma chave de API do Google Cloud com a API Custom Search habilitada e um ID de Mecanismo de Pesquisa Programável (cx).

1. Obtenha uma chave de API e um ID de mecanismo.
2. Adicione o servidor ao seu aplicativo de IA.
3. Faça a pergunta somente leitura acima.

codex mcp add google-custom-search \
  --env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
  --env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
  -- npx -y mcp-google-custom-search@latest

codex mcp list

claude mcp add \
  --env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
  --env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
  --transport stdio --scope user google-custom-search \
  -- npx -y mcp-google-custom-search@latest

claude mcp list

{
  "mcpServers": {
    "google-custom-search": {
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
      }
    }
  }
}

{
  "mcpServers": {
    "google-custom-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
      }
    }
  }
}

{
  "servers": {
    "google-custom-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "${input:custom_search_api_key}",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "${input:custom_search_engine_id}"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "custom_search_api_key", "description": "Google Cloud API key", "password": true },
    { "type": "promptString", "id": "custom_search_engine_id", "description": "Programmable Search Engine id (cx)" }
  ]
}

O que você pode pedir

Pesquisar na web

• Encontre tutoriais recentes sobre um tópico e resuma os principais resultados.
• Pesquise apenas dentro de docs.python.org — ou em todos os lugares, exceto em um site que você não confia.
• Mostre a próxima página de resultados para a mesma consulta.

Refinar os resultados

• Apenas páginas em inglês publicadas no último mês.
• Apenas arquivos PDF; exija uma frase exata ou exclua um termo.
• Restrinja ao conteúdo de um país ou a material com direitos de uso específicos.

Encontrar imagens

• Encontre fotos grandes sobre um tópico, com dimensões e miniaturas.
• Apenas clipart ou desenhos de linha, em preto e branco.
• Mostre a página de onde cada imagem vem.

Ir além das ferramentas tipadas

• Chame a API com parâmetros que as ferramentas tipadas não expõem — fields para reduzir a resposta, lowRange/highRange, hq.
• Obtenha o envelope de resposta bruto com promoções e o pagemap completo.

Como uma pesquisa funciona

1. Toda consulta passa por um Mecanismo de Pesquisa Programável, identificado pelo seu ID cx — o padrão configurado ou um engine_id por chamada. A configuração do mecanismo decide a cobertura: uma lista de sites específicos ou a web inteira quando "Pesquisar em toda a web" está habilitado.
2. Os resultados voltam normalizados — título, URL, trecho e metadados — com cursores next_start/previous_start para paginação. total_results é a estimativa do Google e pode diminuir durante a paginação.
3. A API retorna no máximo 10 resultados por chamada e 100 por consulta (start + num - 1 deve ser ≤ 100). O servidor rejeita uma janela maior antes da solicitação — a API responderia 400 após gastar uma unidade de cota.
4. A pesquisa de imagens exige Pesquisa de imagens habilitada no painel de controle do mecanismo; caso contrário, a API responde 400.

Um corrected_query na resposta é apenas uma sugestão de ortografia — os resultados ainda são para a consulta original. E isto é Pesquisa Programável, não o Google Search Console: a API não pode informar como seu próprio site é indexado ou classificado.

O que pode mudar

Toda ferramenta carrega a anotação de somente leitura, incluindo a saída de escape. A API JSON do Custom Search é um único endpoint GET sem escritas, então a única coisa que uma chamada gasta é uma unidade da sua cota diária.

Obtendo acesso

O Google Custom Search autentica com uma chave de API; não envolve OAuth nem escopos.

1. Crie ou selecione um projeto do Google Cloud e habilite a API Custom Search.
2. Crie uma chave de API em APIs e serviços → Credenciais. Restringir a chave à API Custom Search é um bom hábito.
3. Crie um Mecanismo de Pesquisa Programável no painel de controle e copie o ID do mecanismo de pesquisa (cx). Habilite Pesquisar em toda a web para pesquisa na web aberta e Pesquisa de imagens para a ferramenta de imagens.

Trate a chave de API como uma senha. O servidor a envia no cabeçalho X-Goog-Api-Key, nunca em uma URL, então URLs registradas ou ecoadas não podem vazá-la.

Configuração

Sem credenciais, o servidor ainda inicia e conclui o handshake MCP; a primeira chamada de ferramenta explica exatamente quais variáveis definir. A única configuração malformada é um ID de mecanismo sem chave de API — a chave não pode ser fornecida por chamada, então ambas devem ser definidas juntas.

Dados, limites e trabalho em segundo plano

• As solicitações vão para o Google. O servidor local chama a API JSON do Custom Search. Sua telemetria anônima contém um ID de instalação, versão do pacote, cliente de IA e versões de plataforma, e nomes de ferramentas — nunca a chave de API, consultas de pesquisa, resultados ou argumentos de ferramentas. Defina ASKADS_TELEMETRY=0 para optar por não participar.
• O Google aplica uma cota diária. Toda chamada de qualquer uma das três ferramentas custa uma unidade da cota por projeto — 100 consultas por dia gratuitas, até 10.000 por dia com cobrança. Em 429, o servidor recua honrando Retry-After; como toda a API consiste em GETs idempotentes, 5xx e erros de rede também são repetidos, enquanto 400/403 falham rapidamente.
• Não há sondagem em segundo plano. O servidor é executado apenas quando chamado. Se seu aplicativo de IA suportar tarefas agendadas, ele pode reexecutar uma pesquisa periodicamente — cada execução ainda gasta unidades de cota.

Documentação técnica

• Catálogo de capacidades MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas e entradas
• Documentação de desenvolvimento
• Documentação de publicação
• Referência da API JSON do Custom Search

Suporte

Encontrou um bug ou precisa de um cenário? Crie um problema ou escreva no Telegram.

Você chegou ao fim!