gemini-grounding-mcp

Servidor MCP (Model Context Protocol) que dá ao Claude — e a qualquer cliente compatível com MCP — busca web com grounding do Google Gemini (Google Search), retornando a resposta acompanhada das fontes citadas.

Por que este servidor

• Saída enxuta. Devolve só o texto + a lista de fontes. Implementações comuns anexam o bloco de HTML/CSS da "search box" do Google, que pode representar ~50% do payload e desperdiçar tokens do cliente. Aqui esse lixo é descartado.

• Protocolo limpo. Todo log vai para stderr. O stdout é reservado ao protocolo MCP — escrever nele corromperia a conexão.

• Uma dependência de IA. Usa o SDK oficial @google/genai.

Related MCP server: Google Search MCP

Manual didático para iniciantes

Nunca usou o Terminal? Siga o passo a passo completo, com explicações aula por aula:

• Manual didático (Markdown)

• Manual didático (PDF)

• Painel de apresentação (PDF, formato slides)

• Manual de instalação resumido (PDF, 4 páginas)

Requisitos

• Node.js 18+

• Uma chave de API do Gemini (gratuita): https://aistudio.google.com/apikey

Instalação

git clone https://github.com/wall-e-assessor/gemini-grounding-mcp.git
cd gemini-grounding-mcp
npm install
npm run build

Isso gera o executável em dist/index.js.

Configuração da chave

O servidor lê a chave da variável de ambiente GEMINI_API_KEY.

• Em produção (via cliente MCP): passe a chave na configuração do cliente (veja abaixo) — você não precisa de arquivo .env.

• Para testar localmente: copie .env.example para .env, preencha a chave e rode:

  npm run dev

  (usa o --env-file nativo do Node; nenhuma dependência extra.)

⚠️ Nunca faça commit do seu .env nem exponha a chave. O .gitignore já bloqueia o .env.

Usar no Claude Code

Registre o servidor no escopo de usuário (vale para todas as sessões). Troque o caminho e a chave pelos seus:

As opções (--scope, --env, --transport) vêm antes do nome do servidor. Se o nome vier logo depois de --env, o CLI o lê como mais uma variável e recusa o comando; por isso o --transport stdio fica entre os dois (documentação oficial).

claude mcp add --scope user \
  --env GEMINI_API_KEY=SUA_CHAVE_AQUI \
  --transport stdio \
  gemini-grounding \
  -- node /caminho/absoluto/para/gemini-grounding-mcp/dist/index.js

No Windows (Prompt de Comando), use o caminho completo do node, com cada caminho entre aspas. No PowerShell, troque o ^ do fim das linhas por `. Exemplo:

claude mcp add --scope user ^
  --env GEMINI_API_KEY=SUA_CHAVE_AQUI ^
  --transport stdio ^
  gemini-grounding ^
  -- "C:\Program Files\nodejs\node.exe" "C:\caminho\gemini-grounding-mcp\dist\index.js"

Reinicie o cliente para que a ferramenta apareça.

Configuração equivalente em JSON

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "node",
      "args": ["/caminho/absoluto/para/gemini-grounding-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "SUA_CHAVE_AQUI"
      }
    }
  }
}

Ferramenta exposta

search_with_grounding

Retorno: texto da resposta seguido de uma seção Fontes: com título — URL de cada fonte.

Aviso

As respostas vêm de um modelo de linguagem com busca. Trate-as como dado a verificar, não como verdade absoluta — confirme fatos críticos na fonte oficial.

Autor

@pro.hudsontravassos

Licença

MIT