@brobertoblanko/gemini-grounding-mcp

v1.3.0

Published

a month ago

Minimal MCP server for Google web search via the Gemini API with grounding, inline citation markers and a token footer.

Gemini Grounding MCP

Give Claude Code and other MCP clients current Google Search results through the Gemini API - with inline citation markers and a numbered source list under every answer.

Use it when an assistant needs web-grounded research instead of relying on training data alone. It builds on nothing but the official @google/genai and @modelcontextprotocol/sdk packages, pinned to exact versions.

Scope of use: research queries only. Not intended for production workloads or for connecting to sensitive systems.

What it offers

Citations you can check. Markers such as [1] sit in the answer text, numbered to match the source list below it. A marker can be missing, but it is never placed where the API does not support it - so an unmarked sentence is a reason to look closer.
The queries Gemini actually ran. The footer lists what was typed into Google, which answers what no source list can: whether the search covered your question at all.
Token usage for every call, split into input, output and thinking tokens. What they cost is on Google's pricing page.
Model and thinking level are yours to set. Both persist, both can be overridden for a single request, and both are read at call time, so a change applies to the next answer rather than after a client restart. The thinking level is the main lever on how many tokens a query consumes.
An optional backup model. Gemini's overload is model-dependent, so you can name a second model that the same request goes to once the retries are used up. Off unless you set it, never a model of the server's choosing, and the footer says whenever it stood in.
Failures stay visible. An answer cut off at the token limit or stopped by a filter is marked as such, dropped citation markers are counted, and a failing model returns an error rather than quietly switching to something you did not choose.
Search, URL Context and Code Execution in one call. Gemini can read a page you name and run code; if it did, the code and its output are part of the answer. The only instruction the server adds is today's date - what gets researched follows from your question.
A command line tool on the same core. Verify your API key and model choice before registering the server, and read the full error text when a call fails.

What an answer looks like

Question: "Which Node.js version is currently LTS?"

The current Node.js release versions are as follows [1]:

* Latest LTS: v24.18.1 (recommended for most users)
* Latest Current release: v26.5.1

Sources:
[1] nodejs.org - https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQG52u...

---
🔢 30 input / 86 output / 0 thinking tokens | 🔍 1 sources | 🤖 gemini-flash-latest (thinking: minimal)
🔎 Searched: Node js latest LTS version

The redirect URL is abbreviated here for readability; the real output carries it in full.

Quick start

Nothing to install up front: the client starts the server through npx, which fetches the package on first use and caches it - only that first call takes a few seconds longer. A permanent install is optional and mainly of interest for the command line tool (see Installing globally).

1. Set your API key

The key is passed exclusively through the GEMINI_API_KEY environment variable, never in code and never in the config file. It has to be set persistently, before the client starts the server.

Windows (PowerShell, user scope, once):

[Environment]::SetEnvironmentVariable('GEMINI_API_KEY', '<your-api-key>', 'User')

Reopen the shell afterwards so the variable is available.

macOS / Linux - add to ~/.zshrc, ~/.bashrc or equivalent:

export GEMINI_API_KEY='<your-api-key>'

2. Register the server

Windows (PowerShell):

claude mcp add gemini-grounding -s user `
  -e 'GEMINI_API_KEY=${GEMINI_API_KEY}' `
  -- npx -y @brobertoblanko/gemini-grounding-mcp

macOS / Linux (bash / zsh):

claude mcp add gemini-grounding -s user \
  -e 'GEMINI_API_KEY=${GEMINI_API_KEY}' \
  -- npx -y @brobertoblanko/gemini-grounding-mcp

Write ${GEMINI_API_KEY} in single quotes so your shell does not expand it itself. Claude Code resolves it later, when it loads its configuration - that way only the placeholder ends up in ~/.claude.json, not the key in plain text.

3. Verify

claude mcp list

Then start a new conversation and ask "Which Node.js version is currently LTS?". The reply should look like the example above: citation markers in the text, a source list, and the footer. The server appends that footer to every answer it produces, so if there is none, the tool was not called at all and you are reading the model's own memory.

Run the same query through the command line tool, which needs no installation of its own:

npx -p @brobertoblanko/gemini-grounding-mcp gemini-grounding "your query"

It prints the full error including the original Google API message, which the MCP server has to condense into a single line for the client. An ApiError: {"error":{"code":503, ...}} means the request did not get through to Google, which is a different problem from a broken installation. That one is worth simply retrying: 503 is temporary overload on Google's side, and the server already tries such a request up to four times on its own before reporting it - which is also why an answer can take some ten seconds longer than usual when the service is busy. A call that is still running after 290 seconds is ended on purpose: the server gives Google that deadline, so an overlong run comes back as a 504 naming a reason instead of a connection that drops without one.

Requirements

Node.js 22 or newer - the oldest release still receiving security updates. Check with node -v. The dependencies would technically still run on Node 20, but it reached end-of-life in April 2026, so it is not supported here.
A Gemini API key, available for free at Google AI Studio.
Claude Code or any other MCP-capable client (Model Context Protocol).

A note on cost: Gemini API calls are not free in every case. There is a free tier with rate limits; beyond that you are billed per token, and Google Search grounding may be charged separately depending on model and plan. The official pricing and rate limit pages are authoritative - both change regularly, which is why no concrete figures appear here. The token footer under every answer makes the consumption of each individual call visible.

Tools

gemini-search - research via Google Search, URL Context and Code Execution in one call. Besides the query it accepts an optional model and thinkingLevel that apply to this one call; left out, the saved defaults are used, and naming a model also disables the backup for that call. The answer contains inline citation markers, a source list and a token footer. If Gemini executed code, the code and its result appear under Code execution: after the answer text - the calculation is evidence, so it belongs where the sources are. If the answer did not finish normally, a line marked ⚠️ says so along with the reason.
gemini-list-models - lists the models available for your API key with their token limits. By default a hand-picked shortlist of those suited to research here; all: true shows every model with a status column saying why it is off the list.
gemini-set-model - persists the default model, the default thinking level and/or the backup model (only those values, never the API key). The answer names what was written and the resulting configuration in full, so which models are in force is never something to be guessed at.

Two filters narrow it. The first keeps what generates text and accepts a thinking level, going by what the API reports about each model rather than by its name. The second is models-excluded.js, a hand-maintained list of models that pass the first and still make no sense here: image generation, text-to-speech, robotics, the Deep Research pipeline, models that answer without a single source, and retired ones that reply 404 ... is no longer available. Not one of them would answer a research question better than what is left.

Nothing is lost, only moved. all: true shows every model with a status column naming why it is off the list, and any model id can still be set - the shortlist decides what is shown, not what is allowed.

How the list is maintained and what keeps it honest: specs.md.

Citations and searches

Citation markers

Markers appear in groups such as [1][3] when several sources support the same passage. A sentence carrying none may well come from the model's own memory rather than from the search - precisely the kind of sentence you would not want to write code against unchecked.

Markers are verified against the text segment the API supplies. If the computed span does not match what the API names as the supported passage, the marker is dropped rather than guessed. Whenever that happens, the footer says so - a missing marker would otherwise be misread as "not backed by a source".

They are never placed inside code spans or fenced blocks. A [3] in the middle of copy.replace(obj, x=1) would produce syntactically valid, factually wrong code.

Sources are deduplicated and renumbered accordingly. The API returns search hits, not sources: one measured answer had 17 hits for 14 unique URLs, and naive numbering would have produced markers pointing nowhere.

Full details in specs.md.

Why the source URLs are long

Google hands out its sources as redirect URLs, and the server passes them on unchanged. Shortening or resolving them is not permitted under the terms for Google Search grounding, so it does not happen: the length is deliberate rather than missing polish.

Which searches were actually run

Very broad questions produce a lot of searches, so the footer's last line is capped at roughly 300 characters and ends with (+n more) when there were more. If the line is missing entirely, no search was run.

Asked to compare six web frameworks by version and bundle size, Gemini searched six times for <framework> current version and once for bundle sizes. Rendering strategy and learning curve were answered from its own knowledge. Nothing in the answer itself gave that away - the source list was long and every sentence looked equally well supported.

Command line tool

The server can also be driven without an MCP client - useful for checking that your API key and model choice work before registering it, and for testing a change during development without restarting the client.

The short command gemini-grounding exists once the package is installed globally. If you registered the server through npx, nothing was installed and the same commands run like this instead:

npx -p @brobertoblanko/gemini-grounding-mcp gemini-grounding config

-p names the package, the argument after it the command. Without it, npx @brobertoblanko/gemini-grounding-mcp starts the MCP server rather than the CLI - it then waits silently on stdio, which looks like a hang.

| Command | Effect | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | gemini-grounding "<query>" | Search using the saved defaults; --model <id> and --thinking <level> apply to this call only | | gemini-grounding config | Shows the saved default and backup model with their thinking levels, whether an API key is present, where the config file lives, and the installed version | | gemini-grounding models [--all] | Lists the models suggested for use here with their token limits; --all lists every one with a status column | | gemini-grounding set-model <id> | Persists the default model; add --thinking <level> to save both in one call | | gemini-grounding set-thinking <level> | Persists the default thinking level (minimal, low, medium, high); --model <id> saves both | | gemini-grounding set-backup <id\|off> | Persists a model to retry a failed request with; --thinking <level> gives it its own level, on its own it changes only that level | | gemini-grounding help | Short help | | gemini-grounding version | Prints the installed version |

Which model and thinking level a call actually used is shown in the footer under every answer. Every save prints the resulting configuration, so a change never has to be followed by config:

$ gemini-grounding set-backup gemini-3.5-flash
Saved - Backup: gemini-3.5-flash, Backup thinking level: inherited from the call

Primary: gemini-flash-latest · high
Backup:  gemini-3.5-flash · high (inherited)

The MCP server's gemini-set-model answers with the same two lines.

Shared configuration. The CLI and the MCP server read and write the same config file. A set-model in the terminal therefore also changes what the MCP server uses on its next call - intentionally so, because it makes a model switch possible without having to ask the client to do it.

Argument handling, error output, npm link, and migrating from an older clone: see the CLI documentation, also available in German.

Client configuration

The commands in the quick start cover Claude Code. Other clients that support local stdio servers need the equivalent entry in their own configuration:

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "npx",
      "args": ["-y", "@brobertoblanko/gemini-grounding-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

One caveat: expanding ${GEMINI_API_KEY} from the surrounding environment is a Claude Code feature, not part of the MCP standard. A client without variable expansion will send the placeholder to the API verbatim and the request will fail. If yours does not expand variables, consult its documentation for how it handles secrets rather than pasting the key here.

Installing globally

To install the package permanently instead of fetching it via npx:

npm install -g @brobertoblanko/gemini-grounding-mcp

This puts two commands on your PATH: gemini-grounding-mcp starts the MCP server over stdio, and gemini-grounding is the command line tool.

The trade-off is the usual one: the version stays put until you run npm update -g, which is an advantage when you want a known state and a chore otherwise.

Registration then names that command directly, without npx.

Windows (PowerShell):

claude mcp add gemini-grounding -s user `
  -e 'GEMINI_API_KEY=${GEMINI_API_KEY}' `
  -- gemini-grounding-mcp

macOS / Linux (bash / zsh):

claude mcp add gemini-grounding -s user \
  -e 'GEMINI_API_KEY=${GEMINI_API_KEY}' \
  -- gemini-grounding-mcp

For another client, command becomes the installed command and args can be dropped:

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "gemini-grounding-mcp",
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

To work from the source:

git clone https://github.com/brobertoblanko/gemini-grounding-mcp.git
cd gemini-grounding-mcp
npm install

Then use node <path-to-repo>/index.js as the command. claude mcp add needs a concrete absolute path that resolves on the machine in question.

Removing it

claude mcp remove gemini-grounding

That unregisters the server; with npx nothing else was installed. A global install is removed with npm uninstall -g @brobertoblanko/gemini-grounding-mcp. If you ever saved a default, its file stays behind - see Where settings are stored.

Data and privacy

Search queries, and anything included in a request, are sent to the Gemini API and processed under Google's applicable terms and data handling policies.

This server adds no anonymization and no enterprise data isolation. Do not use it with confidential, personal or regulated data unless you have verified that the service terms and your configuration are appropriate for it.

Where settings are stored

gemini-set-model and the CLI's set-* commands write the default model, thinking level and backup model to:

| Platform | Location | | -------------------------------- | --------------------------------------------------- | | Linux, macOS | ~/.config/gemini-grounding-mcp/config.json | | Windows | %APPDATA%\gemini-grounding-mcp\config.json | | Any, if XDG_CONFIG_HOME is set | $XDG_CONFIG_HOME/gemini-grounding-mcp/config.json |

Neither the file nor its directory is created until you save a setting for the first time. Delete the file to return to the built-in defaults (gemini-flash-latest, thinking level medium, no backup model). It holds nothing but model names and thinking levels - never the API key. Run gemini-grounding config to see the exact path on your machine.

Documentation

specs.md - architecture and design decisions, also in German
cli.md - the command line tool in detail, also in German
google_errors.md - what each Gemini API error code means, whether it is retried and what it costs, also in German
CLAUDE.md - working rules for Claude Code in this repository (German)

License

MIT