Google Search MCP

Um servidor leve de Model Context Protocol (MCP) que permite que modelos de IA pesquisem na web usando a API Google Custom Search.

GitHub
1

Documentação

Node.js TypeScript MCP Google Custom Search License

Listed on mcpservers.org

🔍 Um servidor MCP que permite que qualquer cliente de IA compatível com MCP pesquise na web ao vivo através da API JSON de Pesquisa Personalizada do Google — via stdio, plug-and-play.

🧭 Sumário

✨ Visão Geral

Este servidor preenche a lacuna entre agentes de IA e conhecimento web em tempo real. Ele fala o Model Context Protocol (MCP) via stdio, para que qualquer cliente compatível possa chamar uma única ferramenta — search_google — e receber resultados de pesquisa limpos e estruturados diretamente do Google.

┌─────────────────┐        stdio (MCP)        ┌──────────────────────┐        HTTPS        ┌───────────────────┐
│   MCP Client     │ ───────────────────────▶ │  Google Search MCP    │ ──────────────────▶ │  Google Custom     │
│ (Claude, etc.)   │ ◀─────────────────────── │       Server           │ ◀────────────────── │  Search JSON API   │
└─────────────────┘        results            └──────────────────────┘       results        └───────────────────┘

⚙️ Requisitos

RequisitoDetalhes
🟢 Node.jsv18 ou mais recente
🔑 Chave da API do GoogleCom acesso à API JSON de Pesquisa Personalizada
🆔 ID do Mecanismo de BuscaDe um Mecanismo de Pesquisa Programável do Google (cx)

🔧 Configuração da Pesquisa Personalizada do Google

  1. Crie um projeto no Google Cloud Console
  2. Ative o Custom Search API para esse projeto
  3. Gere uma chave de API
  4. Crie um Mecanismo de Pesquisa Programável e copie seu ID do Mecanismo de Busca

⚠️ Limites de Taxa e Cota

O nível gratuito da API JSON de Pesquisa Personalizada do Google permite 100 consultas por dia. Quando esse limite é atingido, a API retorna um erro 429 e o search_google responderá com uma mensagem de erro em vez de resultados.

  • Precisa de mais? Você pode ativar a cobrança no seu projeto do Google Cloud para até 10.000 consultas/dia (pagas, com preço por consulta).
  • Verifique seu uso atual no Google Cloud Console em APIs & Services → Custom Search API → Quotas.

📦 Instalação

npm install

Crie um arquivo .env na raiz do projeto:

GOOGLE_API_KEY=your_google_api_key
SEARCH_ENGINE_ID=your_search_engine_id

⚠️

Nunca envie o .env nem exponha sua chave de API no controle de versão.

▶️ Executar

Desenvolvimento (execute TypeScript diretamente):

npm start

Produção (compile e depois execute a saída compilada):

npm run build
node build/index.js

ℹ️ O servidor registra status e erros no stderr, mantendo o stdout limpo para mensagens do protocolo MCP.

🐳 Executar com Docker

Prefere contêineres? Você pode compilar e executar este servidor sem instalar o Node.js localmente.

Compile a imagem:

docker build -t google-search-mcp .

Execute-o (certifique-se de que seu arquivo .env esteja configurado primeiro — veja Instalação):

docker run -i --rm --env-file .env google-search-mcp

⚠️

A flag -i é obrigatória — este é um servidor MCP baseado em stdio e precisa de um fluxo interativo para se comunicar com o cliente.

Ou use Docker Compose:

services:
  google-search-mcp:
    build: .
    stdin_open: true
    tty: true
    env_file:
      - .env

docker compose up --build

Aponte seu cliente MCP para o Docker

{
  "mcpServers": {
    "google-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", ".env", "google-search-mcp"]
    }
  }
}

🔌 Configuração do Cliente MCP

Após compilar o projeto, registre o servidor com um cliente compatível com MCP usando o ponto de entrada compilado:

{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": ["/absolute/path/to/Google-Search-MCP/build/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key",
        "SEARCH_ENGINE_ID": "your_search_engine_id"
      }
    }
  }
}

Ou mantenha as credenciais no .env do projeto e inicie a partir do diretório do projeto:

{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": ["/absolute/path/to/Google-Search-MCP/build/index.js"]
    }
  }
}

🧩 Usando Este Servidor no Seu Próprio Projeto

Este servidor não está vinculado a um único cliente — qualquer host compatível com MCP pode iniciá-lo e chamar o search_google. Para usá-lo em outro lugar:

  1. Clone e compile este repositório (ou puxe a imagem Docker — veja Executar com Docker).
  2. Aponte a configuração do seu cliente MCP para o ponto de entrada compilado (build/index.js) ou o comando Docker, usando o mesmo JSON mostrado em Configuração do Cliente MCP.
  3. Clientes suportados — qualquer ferramenta que fale MCP via stdio funciona, incluindo:
    • Claude Desktop
      • Cursor (.cursor/mcp.json)
      • Cline (configurações da extensão do VS Code)
      • Agentes personalizados construídos diretamente com o MCP SDK
  4. Chamando programaticamente — se você está construindo seu próprio cliente/agente MCP em código, conecte um Client MCP via StdioClientTransport apontado para build/index.js, depois chame a ferramenta search_google como qualquer outra ferramenta MCP. Veja a documentação do SDK TypeScript do MCP para exemplos do lado do cliente.

Cada cliente tem seu próprio local e formato de arquivo de configuração para mcpServers — verifique a documentação desse cliente para saber exatamente onde colar o bloco JSON.

🛠️ Ferramenta Disponível

search_google

Pesquisa no Google Custom Search pela consulta fornecida e retorna os 3 principais resultados.

Entrada

{
  "query": "latest TypeScript release"
}

Saída

Cada resultado inclui:

  • 📌 title
  • 🔗 link
  • 📝 snippet

Se nada for encontrado, a ferramenta responde com No results found.

🧪 Testar com o MCP Inspector

npm run build
npx @modelcontextprotocol/inspector node build/index.js

Certifique-se de que suas variáveis de ambiente estejam definidas antes de iniciar o inspector.

📁 Estrutura do Projeto

📦 Google-Search-MCP
├── 📂 src
│   └── index.ts     # MCP server implementation
├── 📂 build          # Compiled JavaScript and type declarations
├── .env              # Local environment config (not committed)
└── README.md

🤝 Contribuindo

Contribuições, relatórios de bugs e solicitações de recursos são bem-vindos!

  • Encontrou um bug ou tem uma ideia? Abra uma issue descrevendo-o.
  • Quer contribuir com código?
    1. Faça um fork do repositório 2. Crie uma branch (git checkout -b feature/your-feature) 3. Faça suas alterações e teste localmente (npm start ou docker compose up --build) 4. Faça commit e push, depois abra um Pull Request

Por favor, mantenha os PRs focados — um recurso ou correção por PR facilita a revisão.

📄 Licença

Este projeto está licenciado sob a Licença MIT.

Listed on mcpservers.org