Run Claude Code with Google Gemini for Free: A Complete Step‑by‑Step Guide

Why use Gemini with Claude Code

Gemini provides a free tier that is significantly cheaper than Claude, faster response times, and a context window of up to 1 million tokens (about five times larger than Claude).

Obtain a Gemini API key

Access Google AI Studio

Open Google AI Studio (https://aistudio.google.com) and sign in with a Google account.

Create the API key

In the left‑hand menu click Get API key , then Create API key → Create API key in new project . Copy the generated key immediately; it is shown only once.

AIzaXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Free quota

Gemini 2.5 Pro – 5 requests/min, 100 requests/day – suited for complex reasoning.

Gemini 2.5 Flash – 10 requests/min, 250 requests/day – ideal for daily development.

Gemini 2.5 Flash‑Lite – 15 requests/min, 1000 requests/day – best for high‑frequency calls.

The quota resets at midnight Pacific Time.

Configure Claude Code to use a third‑party endpoint

Claude Code expects Anthropic‑compatible API calls, while Gemini uses Google’s format. Two integration approaches are available:

Use a proxy service that translates Claude‑style requests to Gemini (e.g., laozhang.ai, OpenRouter).

Integrate Gemini directly via the Model Context Protocol (MCP).

Prepare configuration files

Create a dummy primary API key file to bypass Claude’s validation:

# macOS / Linux
mkdir -p ~/.claude
echo '{"primaryApiKey": "any-string-is-ok-here"}' > ~/.claude/config.json

# Windows PowerShell
$path = "$HOME\.claude"
New-Item -ItemType Directory -Path $path -Force | Out-Null
Set-Content -Path "$path\config.json" -Value '{"primaryApiKey": "any-string-is-ok-here"}'

Skip the onboarding flow:

# macOS / Linux
echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

# Windows PowerShell
Set-Content -Path "$HOME\.claude.json" -Value '{"hasCompletedOnboarding": true}'

Proxy service configuration (example: laozhang.ai)

Obtain an API key from laozhang.ai after registration.

Edit ~/.claude/settings.json (create if missing) with the following content:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.laozhang.ai/v1",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_LAOZHANG_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}

Set the environment variables for the current shell:

# Bash (macOS / Linux
export ANTHROPIC_BASE_URL="https://api.laozhang.ai/v1"
export ANTHROPIC_AUTH_TOKEN="YOUR_LAOZHANG_API_KEY"

# PowerShell (Windows)
$env:ANTHROPIC_BASE_URL = "https://api.laozhang.ai/v1"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_LAOZHANG_API_KEY"

Verify the setup

Open a new terminal (environment variables are only loaded in new shells) and run: claude After the welcome screen, type /status to view the active model and endpoint, for example:

Model: gemini-2.5-flash
Endpoint: https://api.laozhang.ai/v1

Advanced integration via MCP

Install the MCP server

# Clone the repository
git clone https://github.com/Raydius/gemini-for-claude-mcp.git
cd gemini-for-claude-mcp

# Install dependencies
npm install
npm run build

Add the MCP plugin to Claude Code

claude mcp add gemini \
  -e GEMINI_API_KEY=YOUR_GEMINI_API_KEY \
  -e GEMINI_DEFAULT_MODEL=gemini-2.5-flash \
  -- node /absolute/path/gemini-for-claude-mcp/dist/app.js

Using the MCP plugin

Invoke Gemini through Claude Code with natural‑language prompts, e.g.:

Help me explain Rust's ownership model with Gemini.

Claude forwards the request to Gemini and returns the result.

Model selection guidance

Simple scripts / rapid prototyping – Gemini 2.5 Flash‑Lite

Daily development & debugging – Gemini 2.5 Flash

Complex tasks & code review – Gemini 2.5 Pro

Ultra‑long context processing – Gemini 1.5 Pro

Common issues

429 – quota exceeded

Reduce request frequency, switch to a model with a larger quota (e.g., Flash‑Lite), or wait for the daily reset.

Access from Mainland China

Google AI Studio is blocked; use a VPN or a proxy service such as laozhang.ai to reach Gemini.

Configuration changes not taking effect

Restart the terminal so environment variables are loaded.

Ensure ~/.claude/settings.json exists at the correct location.

Verify the API key is correct.

Check the base URL spelling.

Free quota exhausted

Wait for the next day’s reset.

Upgrade to a paid tier if additional calls are required.