Skip to main content
Glama
Sign In
gemini-grounding-mcp

gemini-grounding-mcp

by wall-e-assessor
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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: Deno Gemini Grounding MCP Server

Manual didático para iniciantes

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

Requisitos

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.

Variável

Obrigatória

Padrão

Descrição

GEMINI_API_KEY

sim

—

Chave do Google AI Studio

GEMINI_MODEL

não

gemini-2.5-flash

Modelo do Gemini

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

Parâmetro

Tipo

Obrigatório

Descrição

query

string

sim

A pergunta ou termo a pesquisar

context

string

não

Contexto adicional para orientar a resposta

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

Available Tools

1 tool
search_with_groundingBusca com grounding (Gemini)A

Busca informação atual na web usando o grounding (Google Search) do Google Gemini e retorna a resposta com a lista de fontes citadas. Saída enxuta: apenas texto + fontes.

NameRequiredDescriptionDefault
queryYesA pergunta ou termo a pesquisar.
contextNoContexto adicional opcional para orientar a resposta.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full behavioral burden. It usefully discloses the output format ('Saída enxuta: apenas texto + fontes') and that sources are cited, but says nothing about latency, cost/quota, whether grounding always triggers a web search, or freshness guarantees. Some transparency, clearly incomplete for a web-facing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly packed sentences: the first gives purpose and mechanism, the second front-loads the output contract. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter search tool with full schema coverage and an explicit return-shape statement, the description is essentially complete. It lacks only operational context (quota, freshness, grounding behavior) that would matter for a tool with no annotations, preventing a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — both 'query' and 'context' are documented in the schema. The description adds no parameter-level meaning beyond what the schema already says, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (search), resource (current web information), and mechanism (Google Gemini grounding via Google Search), plus the return shape (answer + cited sources). An agent knows exactly what the tool produces. No siblings exist to differentiate, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Busca informação atual na web' implies usage for fresh/current information, but there is no explicit when-to-use/when-not guidance, no mention of alternatives, and no prerequisites. Adequate but leaves selection reasoning implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedsearch_with_grounding
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusing it with another. Its purpose (grounded web search via Google Gemini with cited sources) is unambiguous.

Naming Consistency5/5

The single name search_with_grounding follows a clear snake_case verb-plus-qualifier pattern that describes the operation precisely. There are no competing conventions to conflict with.

Tool Count4/5

A single tool falls below the typical 3-15 range, but the server's stated scope is a single focused operation (grounded search), so one tool genuinely earns its place. A thin surface is defensible here rather than over-scoped.

Completeness4/5

For a grounding-search server, the core operation is covered end to end (query in, answer plus cited sources out). Minor gaps exist, such as a sources-only or raw-search mode and configurable result limits, but agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • Deno Gemini Grounding MCP

    rinerebox1
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides Google search grounding capabilities for Gemini AI models through MCP, enabling AI assistants to perform web searches with Gemini's grounding API for more accurate and up-to-date responses.
    MIT

  • Gemini Research MCP

    claudiusbotticus
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides real-time web research and URL summarization capabilities using Gemini 2.5 Flash with native Google Search grounding. It enables users to perform factual searches and summarize web content directly within MCP-compatible clients like Claude Desktop.
    17
    -

  • searchapi-mcp-server

    Ahmednsh
    A
    license
    A
    quality
    B
    maintenance
    Enables Claude and other MCP clients to run Google Search, Google Shopping, Google Jobs, and YouTube Search queries, returning concise structured text optimized for LLM context instead of raw JSON.
    4
    43 npm
    MIT