gemini-webtools-mcp

TL;DR: MCP server that gives Claude Code web search and fetch capabilities via Gemini's grounded search.

Constraint: Claude Code on Vertex AI has its native WebSearch and WebFetch tools disabled by org policy.

Objective: Provide a drop-in MCP replacement that matches or exceeds native tool quality, with zero Anthropic API dependency.

Overview

This server exposes two MCP tools — gemini_web_search and gemini_web_fetch — that mirror the native Claude Code web tools' input schemas and output formats. Claude Code already prefers MCP-provided tools over its native equivalents, so registration is all that's needed.

• Search uses Gemini's googleSearch grounding tool with inline citations and numbered source attribution. Supports allowed_domains / blocked_domains filtering.
• Fetch retrieves a URL, strips HTML boilerplate (~88% token reduction), and processes content against a user prompt via Gemini. Includes cross-host redirect detection and raw markdown passthrough.
• Both tools share a 15-minute content cache with FIFO eviction, matching native cache behavior. Connection warm-up on startup eliminates cold-start latency.
• Default model is gemini-2.5-flash-lite (configurable via GEMINI_MODEL). Selected after benchmarking 5 Gemini models — best accuracy/speed trade-off.

Setup

claude mcp add gemini-web -e GEMINI_API_KEY=your-api-key -- npx -y gemini-webtools-mcp

Then restart Claude Code. The tools will be available automatically.

| Variable | Required | Default | Description | |---|---|---|---| | GEMINI_API_KEY | Yes | — | Google AI API key | | GEMINI_MODEL | No | gemini-2.5-flash-lite | Gemini model to use | | NODE_EXTRA_CA_CERTS | No | — | Custom CA certificate bundle |

Benchmark

Run the included benchmark (bench.mjs) with GEMINI_API_KEY=... node bench.mjs. Tests 25 search queries across 4 categories and 3 fetch URLs.

Search

| Metric | gemini-webtools-mcp | Native Claude Code | MCPBench Bing | MCPBench Brave | |---|---|---|---|---| | SimpleQA Accuracy | 80% (8/10) | ___ | — | — | | FreshQA Factual | 100% (5/5) | ___ | — | — | | FreshQA False-Premise | 100% (5/5) | ___ | — | — | | Coding QA | 100% (5/5) | ___ | — | — | | Overall Accuracy | 92% (23/25) | ___ | 64% | 48% | | Calibration | 95.8% | ___ | — | — | | Mean Latency | ~1.4s | ___ | — | — | | P95 Latency | ~1.7s | ___ | — | — |

Fetch

| Metric | gemini-webtools-mcp | Native Claude Code | |---|---|---| | Accuracy | 100% (3/3) | ___ | | Mean Latency | ~0.5s | ___ |

Releasing

GitHub and npm are synced automatically via GitHub Actions. When you create a release on GitHub, the workflow publishes to npm.

# 1. Make changes, commit, push
git add -A && git commit -m "description" && git push

# 2. Bump version (patch/minor/major)
npm version patch --no-git-tag-version
git add package.json package-lock.json && git commit -m "v$(node -p 'require(\"./package.json\").version')"

# 3. Tag and push
git tag "v$(node -p 'require("./package.json").version')"
git push && git push --tags

# 4. Create release (triggers npm publish)
gh release create "v$(node -p 'require("./package.json").version')" --generate-notes

The workflow requires an NPM_TOKEN secret (Granular Access Token with read-write on this package) in the repo settings.

License

MIT