Guide · Claude thinks. Gemini reads.

Claude + Gemini via MCP: setup guide

Set up Gemini as an MCP tool in Claude Code, so big reads don't fill Claude's context.

Last updated 26 Oct 2026

How it works. Claude Code calls Gemini through an MCP server (gemini-mcp-tool, which runs the Gemini CLI). When you pass files as @path, Gemini reads them itself and Claude only receives Gemini's answer. The large files never enter Claude's context.

Before you start

Claude Code installed
Node.js 20 or later (node -v)

1Install Gemini CLI

npm install -g @google/gemini-cli

2Add your Gemini API key

Create a key at aistudio.google.com/apikey, save it as a user environment variable, then restart your terminal and your editor.

# Windows (PowerShell)
setx GEMINI_API_KEY "your-key"

# macOS / Linux: add to ~/.zshrc or ~/.bashrc
export GEMINI_API_KEY="your-key"

3Register the MCP server with Claude Code

User scope makes it available in every project. Windows needs cmd /c to run npx.

# Windows
claude mcp add -s user gemini-cli -- cmd /c npx -y gemini-mcp-tool

# macOS / Linux
claude mcp add -s user gemini-cli -- npx -y gemini-mcp-tool

# Check it shows as connected
claude mcp list

4Tell Claude when to use Gemini

Add this to ~/.claude/CLAUDE.md:

## Gemini (MCP)
Use mcp__gemini-cli__ask-gemini instead of reading files yourself when:
- you need to read big logs, docs or folders: pass them as @path so
  Gemini reads them and you only get the summary
- a task touches 5+ files or the architecture is unclear: ask Gemini
  for a plan, save it to GEMINI-PLAN.md, then execute it
Never send secrets, .env files or customer data.

5Test it

In Claude Code, ask:

Use Gemini to summarise @src in 10 bullet points.

You should see Claude call ask-gemini and come back with a short summary.

Why it saves tokens

Example: one big read of a large repo or log file of about 150,000 tokens.

Claude's context	Tokens
Claude reads it itself	~150,000
Claude asks Gemini (request ~200 + summary back ~3,000)	~3,200
Saving on that step	~98%

The saving compounds: whatever sits in Claude's context is carried into every later turn of the session, and a smaller context also means fewer auto-compactions.

These are estimates. Real savings depend on file size and summary length. Gemini still processes the full input, but on its own quota, which has a free tier.

Check before you send code. On the free tier, Google may use your Gemini API prompts to improve its products. Don't send code or data you're not allowed to share, and check your employer's AI policy first.

Next: more ways to save tokens in Claude Code, and how to write a good CLAUDE.md.