An MCP server that gives your assistant one tool: web_search. Ask a
question, and it runs a Google search through Gemini, reads the results, and
hands back a written answer with the sources it used. The model does the
searching and the reading; you get the answer and the links.
It talks to Gemini one of two ways: through Vertex AI (your Google Cloud project) or through AI Studio (an API key). Pick whichever you already have. On Vertex AI it can also use Web Grounding for Enterprise, Google's compliance-grade grounding tool — see Grounding modes.
New here? The companion write-up tells the story behind the tool — why it exists, how the grounding round-trip and citation extraction work, and how the default model was chosen on the evidence: Building gemini-search-mcp: Grounding, Citations, and Choosing a Gemini Model.
flowchart LR
A[MCP client] -->|web_search query| B[gemini-search-mcp]
B -->|GenerateContent + grounding tool| C[Gemini]
C -->|grounded answer + citations| B
B -->|answer + sources| A
The server speaks MCP over stdio, so any MCP client can launch it as a subprocess and call the tool. Which grounding tool it hands to Gemini depends on the grounding mode.
With Go:
go install github.com/cwest/gemini-search-mcp@latestThat drops a gemini-search-mcp binary in your $GOBIN (usually
~/go/bin). Make sure that's on your PATH.
Prefer a prebuilt binary? Grab one from the
releases page,
extract it, and put it somewhere on your PATH.
The server reads everything from the environment. It checks for Vertex AI first; if that isn't set up, it falls back to AI Studio. If neither is configured, it exits at startup with a message telling you what's missing.
Use this if you have a Google Cloud project with Vertex AI enabled.
| Variable | Required | Notes |
|---|---|---|
GOOGLE_GENAI_USE_VERTEXAI |
one of these | Set to true to force Vertex. |
GOOGLE_CLOUD_PROJECT |
yes | Your project id. |
GOOGLE_CLOUD_LOCATION |
yes | e.g. global or us-central1. |
GOOGLE_APPLICATION_CREDENTIALS |
usually | Path to a service-account key file, unless you're already authenticated with application default credentials. |
Setting GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION together is enough
to select Vertex; the GOOGLE_GENAI_USE_VERTEXAI flag is there if you want to
be explicit.
The quick path. Get a key from AI Studio.
| Variable | Required | Notes |
|---|---|---|
GEMINI_API_KEY |
yes | Your AI Studio API key. GOOGLE_API_KEY works too. |
| Variable | Default | Notes |
|---|---|---|
GEMINI_SEARCH_MODEL |
gemini-3.1-flash-lite |
The Gemini model to query. See Which model? for why this is the default. |
GEMINI_SEARCH_TIMEOUT |
30s |
Per-search deadline, as a Go duration (45s, 2m). |
GEMINI_GROUNDING_MODE |
google_search |
Which grounding tool to use: google_search (default) or enterprise. enterprise requires Vertex AI. See Grounding modes. |
One caveat worth knowing: on Vertex AI the source list includes the domain for each citation. On AI Studio that field comes back empty, so you'll see the page title and URL but not a bare domain.
Grounding is how the model backs its answer with real web sources. This server
supports three distinct paths, selected by your provider and the
GEMINI_GROUNDING_MODE variable. The default is unchanged from earlier
versions: google_search on whichever provider you configured.
flowchart TD
Start[web_search] --> Mode{GEMINI_GROUNDING_MODE}
Mode -->|google_search default| GS[google_search tool]
Mode -->|enterprise| ENT[enterpriseWebSearch tool]
GS --> AIS[AI Studio - API key]
GS --> VTX[Vertex AI - project + ADC]
ENT --> VTXE[Vertex AI only - required]
| Path | Provider | GEMINI_GROUNDING_MODE |
What it is |
|---|---|---|---|
| AI Studio + Google Search | AI Studio (API key) | google_search |
Grounding with Google Search, reached via an AI Studio API key. The quick path. |
| Vertex + Google Search | Vertex AI | google_search |
The same Grounding with Google Search tool, reached through your Google Cloud project. |
| Vertex + Web Grounding for Enterprise | Vertex AI | enterprise |
The enterpriseWebSearch tool: a compliance-grade grounding product with no logging of your prompts or responses for product improvement, VPC Service Controls support, and a curated web index. |
These are three different things, and the distinction is real. Reaching
Grounding with Google Search over a Vertex API path is not the same as Web
Grounding for Enterprise — "Vertex" alone does not make grounding "enterprise."
Enterprise grounding is a separate tool (enterpriseWebSearch) with different
data-handling guarantees, and it is available only on Vertex AI. Selecting
GEMINI_GROUNDING_MODE=enterprise without the Vertex provider fails fast at
startup with a message telling you what's required.
To use it, configure Vertex AI (see Vertex AI above — same credentials, no new secrets) and set:
export GEMINI_GROUNDING_MODE=enterpriseFor the product details, data-handling guarantees, and availability, see Web Grounding for Enterprise.
Web Grounding for Enterprise needs a Vertex AI project set up for it:
- APIs enabled on the project: Vertex AI API and the Discovery Engine API (the enterprise index is served through Discovery Engine).
- A region with Gemini quota. In testing, the
globallocation was quota-dry (429RESOURCE_EXHAUSTED);us-central1worked. SetGOOGLE_CLOUD_LOCATIONto a region that has Gemini quota on your project. - A model served in that region. Both
gemini-2.5-flashandgemini-3.5-flashare generally available across regional andglobalendpoints; preview models tend to requireglobal. Availability varies by model and region, so consult the canonical Vertex AI locations documentation rather than assuming, and setGEMINI_SEARCH_MODELto a model available in your chosen region. In our testing,gemini-2.5-flashonus-central1worked.
A working combination for a Vertex project with the APIs above enabled:
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1
export GEMINI_SEARCH_MODEL=gemini-2.5-flash
export GEMINI_GROUNDING_MODE=enterpriseThe live integration tests (RUN_VERTEX_INTEGRATION=1) default to this same
region/model combination so they run green out of the box; both env vars
override the defaults.
The default is gemini-3.1-flash-lite, and that's an evidence-based choice, not a
guess. We built an eval harness (see evals/) that runs a golden
query set through several models and scores the answers with a different model
family as judge (claude-opus-4-8 on Vertex, to avoid self-grading bias). When new
models GA, we re-run the sweep and publish the numbers here — including the ones that
argue against the default, and the vendor claims that didn't hold up.
gemini-3.6-flash and gemini-3.5-flash-lite went GA and are now routable, so we
re-ran the sweep against the current default (24 cases × 3 models = 72 cells, 0
errors). The default does not change: gemini-3.1-flash-lite stays. Full report,
methodology, and per-cell JSON:
evals/results/2026-07-22-default-model-sweep.md.
A grounded-search tool is judged on two independent axes, and it matters not to average them into one cell:
- Coverage — how often the model actually grounds (returns sources) instead of answering from parametric memory. Comparable across all 24 cases.
- Quality when grounded — faithfulness and citation precision/recall/F1. These are only defined on a grounded answer, so they are compared head-to-head only on the cases every model grounded (the common grounded subset), never over each model's own variable-size subset.
Quality on the common grounded subset (apples-to-apples). Restricted to the cases all three models grounded (faithfulness n=10, citation n=9):
| Model | Faithfulness (n=10) | Citation F1 (P / R) (n=9) |
|---|---|---|
| gemini-3.1-flash-lite (default) | 0.934 | 0.476 (0.92 / 0.32) |
| gemini-3.6-flash | 0.905 | 0.610 (0.97 / 0.44) |
| gemini-3.5-flash-lite | 0.810 | 0.474 (1.00 / 0.31) |
On identical inputs the default leads faithfulness (0.934 > 0.905 > 0.810).
gemini-3.6-flash's one real quality win — citation recall / F1 — survives the
common-subset cut (F1 0.61 vs 0.48). The harness computes this intersection
automatically from the run JSON and refuses to rank a conditional metric over
mismatched denominators, so the comparison can't silently drift back to an
apples-to-oranges average.
Coverage and the other comparable, whole-table metrics (all 24 cases):
| Model | Ungrounded (0-source) | Relevance | Correctness | Source qual | p50 latency | Grounded tok/s (mean / median) | Avg tokens/query | $/1k queries* |
|---|---|---|---|---|---|---|---|---|
| gemini-3.1-flash-lite (default) | 4/24 (17%) | 0.91 | 0.82 | 0.59 | 2810 ms | 90 / 89 | 328 | $0.48 |
| gemini-3.6-flash | 13/24 (54%) | 0.92 | 0.84 | 0.35 | 2330 ms | 99 / 81 | 375 | $2.59 |
| gemini-3.5-flash-lite | 11/24 (46%) | 0.93 | 0.83 | 0.36 | 2162 ms | 110 / 79 | 326 | $0.73 |
* Token cost only, at official Vertex Standard-tier Global list prices. It excludes the flat grounded-search surcharge (~$35 / 1k grounded prompts beyond the free tier), which is identical per prompt across all three models and dominates absolute cost.
The ungrounded rate is itself a first-order coverage result. gemini-3.6-flash
answered from parametric knowledge with zero sources on 13/24 cases (54%) —
including speed-of-light, boiling-point-water, and tallest-mountain — versus
4/24 (17%) for the default. For a tool whose whole job is grounded citation,
answering half the queries without searching is the strongest single argument
against 3.6-flash.
Two vendor claims that motivated the eval did not reproduce in this workload:
- "~350 tok/s for Lite" — not reproduced. Measured end-to-end grounded throughput
for
gemini-3.5-flash-litewas ~110 tok/s mean, ~79 tok/s median — ~3× below the claim. (Caveat: these are grounded search calls, so wall-clock includes retrieval and the redirect hop, not pure decode. Lite is the fastest on p50 latency, 2162 ms.) - "~17% token efficiency for 3.6-Flash" — not reproduced (opposite sign).
gemini-3.6-flashused +14.3% more tokens per query than the default, not fewer (375 vs 328). Combined with its higher per-token output price, its token cost per query is ~5.4× the default. (ThinkingBudget=0is enforced for all models, so 3.6-Flash's thinking capability is neutralized in this fast-grounded config — consistent methodology, but the efficiency claim doesn't transfer to this use case.)
The judge for this run is κ-validated against an independent human label set: relevance κ=1.00, source_quality κ=1.00, correctness κ=0.86 — all clear the κ>0.6 trust bar.
Conclusion: keep gemini-3.1-flash-lite as the default. Neither new model beats
it on the core quality axes at a price worth paying — the default leads faithfulness
and source quality and grounds far more reliably. Choose gemini-3.6-flash only if
citation recall is a product priority worth ~5× the token cost.
The original sweep that set the default compared it against gemini-3.5-flash and
gemini-3.1-pro-preview:
| Model | Relevance | Correctness | Source quality | Faithfulness | Cite P/R | p50 latency | $/1k queries |
|---|---|---|---|---|---|---|---|
| gemini-3.1-flash-lite | 0.92 | 0.87 | 0.53 | 0.92 | 0.97 / 0.31 | 2.5 s | $0.69 |
| gemini-3.5-flash | 0.88 | 0.82 | 0.33 | 0.84 | 0.87 / 0.35 | 3.2 s | $2.98 |
| gemini-3.1-pro-preview | 0.71 | 0.69 | 0.34 | 0.78 | 0.86 / 0.38 | 11.0 s | $49.76 |
Flash-Lite matched or beat the larger models on quality while being far faster and cheaper — because for grounded search, answer quality comes mostly from Google Search, not from model size.
The full numbers, methodology, κ-validation, and instructions to reproduce or extend
the harness are in evals/README.md. Pick a different model with
GEMINI_SEARCH_MODEL if your workload disagrees — and if you do, run the eval and
tell us what you found.
Input:
| Field | Type | Description |
|---|---|---|
query |
string | What you want to know, in plain language. |
Output. The tool returns markdown text: the answer, then a numbered list of
sources, then the searches Gemini actually ran. It also returns the same data
in structured form (answer, sources, queries) for clients that prefer to
parse it.
A response looks roughly like this:
Go 1.26.4 is the latest stable release.
Sources:
1. go.dev — Go Downloads
https://go.dev/dl/
2. endoflife.date — Go EOL
https://endoflife.date/go
Searches run: latest Go version
If a search fails, the tool returns an error result with the reason instead of crashing the server, so the session stays alive for the next call.
For Claude Code:
claude mcp add -s user gemini-search -- gemini-search-mcpYour client launches the binary and passes the environment through, so set the provider variables (above) wherever that client reads its environment.
Any MCP client works the same way: point it at the gemini-search-mcp binary
and let it run over stdio.
Instead of registering the server by hand, install gemini-search-mcp as a
Claude Code plugin. The plugin auto-registers the MCP server and ships a skill
that steers the model to prefer this tool for web search.
The plugin lives in this repository, so point Claude Code at it with
--plugin-dir:
claude --plugin-dir /path/to/gemini-search-mcp(Or add it to a marketplace and claude plugin install gemini-search@<marketplace>.)
The plugin's MCP config launches ${CLAUDE_PLUGIN_ROOT}/bin/gemini-search-mcp,
so download a release binary into the plugin's bin/ first:
scripts/install-plugin-binary.sh # latest release
scripts/install-plugin-binary.sh v0.2.0 # a specific tagThe script detects your OS and architecture, downloads the matching GoReleaser
archive from the releases page,
verifies it against checksums.txt, and extracts the binary into bin/. When
Claude Code runs it, CLAUDE_PLUGIN_ROOT is already set; running it by hand
installs next to the plugin instead.
The plugin does not ship any credentials — you supply your own. Set either
the Vertex AI variables (GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT,
GOOGLE_CLOUD_LOCATION, and usually GOOGLE_APPLICATION_CREDENTIALS) or an AI
Studio key (GEMINI_API_KEY) in the environment Claude Code launches from. See
Configuration for the full list.
To make Claude Code prefer this tool over the built-in WebSearch, add
"permissions": {"deny": ["WebSearch"]} to your settings. For that and for
steering other agents (Gemini CLI, opencode, OpenAI-compatible clients), see
docs/prefer-web-search.md.
- Grounding with Google Search — the Gemini API feature this server is built on.
- Web Grounding for Enterprise
— the compliance-grade grounding tool behind
GEMINI_GROUNDING_MODE=enterprise. - Building gemini-search-mcp: Grounding, Citations, and Choosing a Gemini Model — the companion write-up: why the server exists, how the grounding round-trip and citation extraction work in the code, and how the default model was measured.
See CONTRIBUTING.md and our Code of Conduct.
This project is licensed under the Apache-2.0 License.