Gemini MCP Server for Claude Code

Give Claude Code access to Google's Gemini AI models. Get second opinions, compare approaches, and leverage Gemini's capabilities—all from within your Claude Code session.

Table of Contents

• Quick Start

• Features

• Prerequisites

• Installation & Setup

• Using with Claude Code

• Configuration

• Other MCP Clients

• Troubleshooting

• Development

• Tool Reference

• Architecture

• Contributing

• License

Quick Start

# 1. Clone and build
git clone https://github.com/Raydius/gemini-for-claude-mcp.git
cd gemini-for-claude-mcp
npm install && npm run build

# 2. Authenticate to Google Cloud (one-time)
gcloud auth application-default login

# 3. Add to Claude Code (replace project ID and absolute path)
#    GOOGLE_CLOUD_LOCATION is optional and defaults to `global`. The newest
#    preview models (gemini-3-pro-preview, gemini-3.1-pro-preview) require
#    `global` — regional endpoints return 404 for those models.
claude mcp add gemini \
  -e GOOGLE_CLOUD_PROJECT=your-gcp-project-id \
  -e GEMINI_DEFAULT_MODEL=gemini-2.5-pro \
  -- node $(pwd)/dist/app.js

# 4. Start Claude Code and try it out
claude

Then ask Claude:

"Ask Gemini to explain the tradeoffs between microservices and monoliths"

Features

• Built for Claude Code - Seamlessly integrates with your Claude Code workflow

• Streaming Responses - Enabled by default for real-time output

• Multi-turn Conversations - Maintain context across multiple Gemini queries

• Configurable Model - Set your preferred Gemini model via environment variable

• Token Counting - Estimate costs before making queries

• Type-Safe - Built with strict TypeScript

• Well-Tested - 100% domain layer test coverage

Prerequisites

• Claude Code - Installation guide

• Node.js 20+ - Download

• Google Cloud project with the Vertex AI API enabled. See Enable the Vertex AI API.

• IAM role: the principal running this server needs roles/aiplatform.user (or higher) on the project.

• Authentication: either Application Default Credentials via gcloud auth application-default login (recommended for local dev), or a service-account JSON key referenced by GOOGLE_APPLICATION_CREDENTIALS.

• gcloud CLI - Install (only needed for ADC login).

Installation & Setup

Step 1: Clone and Build

git clone https://github.com/Raydius/gemini-for-claude-mcp.git
cd gemini-for-claude-mcp
npm install
npm run build

Step 2: Authenticate to Google Cloud

gcloud auth application-default login

This stores Application Default Credentials that the server uses to call Vertex AI. Alternatively, set GOOGLE_APPLICATION_CREDENTIALS to the path of a service-account JSON key.

Step 3: Add to Claude Code

Option A: Using the CLI (Recommended)

# Basic setup (substitute default model for any valid Gemini model designation string)
# GOOGLE_CLOUD_LOCATION defaults to `global` and is omitted here. See "Vertex AI
# location" below if you need to pin a regional endpoint.
claude mcp add gemini \
  -e GOOGLE_CLOUD_PROJECT=your-gcp-project-id \
  -e GEMINI_DEFAULT_MODEL=gemini-2.5-pro \
  -- node /absolute/path/to/gemini-for-claude-mcp/dist/app.js

Option B: Manual Configuration

Edit your Claude Code settings file (~/.claude.json):

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/absolute/path/to/gemini-for-claude-mcp/dist/app.js"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id",
        "GEMINI_DEFAULT_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

See Configuration for all available options and supported models.

Step 4: Verify Installation

Start Claude Code and verify the server is connected:

claude

Then ask:

"What Gemini models are available?"

If configured correctly, Claude will use the list_gemini_models tool and show you the available models.

Using with Claude Code

Once installed, you can ask Claude to use Gemini in natural language. Here are some examples:

Get a Second Opinion

You: I'm implementing a rate limiter. Can you ask Gemini for its approach?

Claude: I'll query Gemini for an alternative perspective on rate limiting...
[Uses query_gemini tool]

Gemini suggests using a token bucket algorithm. Here's the comparison:
- My approach: Sliding window...
- Gemini's approach: Token bucket with...

Compare Solutions

You: Here's my sorting algorithm. Have Gemini review it and compare approaches.

Claude: Let me get Gemini's analysis of your sorting implementation...
[Uses query_gemini tool]

Gemini's feedback: ...

Leverage Gemini's Strengths

You: Ask Gemini to analyze this mathematical proof for logical errors.

Claude: I'll have Gemini examine the proof...
[Uses query_gemini tool]

Check Token Usage Before Querying

You: How many tokens would this prompt use with Gemini?

Claude: Let me count the tokens...
[Uses count_gemini_tokens tool]

This text would use approximately 1,250 tokens.

Multi-turn Conversations

You: Start a conversation with Gemini about Rust's ownership model.

Claude: [Uses query_gemini tool]
Gemini explains: Rust's ownership model is based on three rules...

You: Ask Gemini to give an example of borrowing.

Claude: [Uses query_gemini with history from previous turn]
Gemini continues: Here's an example of borrowing...

Configuration

Configure the server using environment variables:

Vertex AI location (GOOGLE_CLOUD_LOCATION)

This server defaults to global because the newest preview Gemini models — including gemini-3-pro-preview and gemini-3.1-pro-preview — are only served from the global location. Pointing the client at a regional endpoint (us-central1, europe-west4, etc.) will return a 404 for those models, which surfaces as a GEMINI_MODEL_NOT_FOUND error.

Override GOOGLE_CLOUD_LOCATION only if every model you intend to call is available in that region. Check per-model availability at https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations before pinning a region.

Other MCP Clients

While this server is optimized for Claude Code, it works with any MCP-compatible client.

Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/absolute/path/to/gemini-for-claude-mcp/dist/app.js"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id",
        "GEMINI_DEFAULT_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

Generic stdio Clients

This server uses stdio transport. Start it with:

GOOGLE_CLOUD_PROJECT=your-gcp-project-id \
GEMINI_DEFAULT_MODEL=gemini-2.5-flash \
node dist/app.js

This relies on Application Default Credentials. To use a service-account key instead, also export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json.

The server communicates via stdin/stdout using the MCP protocol.

Development

Available Scripts

Project Structure

src/
├── domain/           # Business logic (zero external dependencies)
│   ├── entities/     # Business objects (GeminiModel, GeminiPrompt, etc.)
│   ├── ports/        # Interfaces for external services
│   ├── use-cases/    # Application logic
│   └── errors/       # Domain-specific errors
├── infrastructure/   # External integrations
│   ├── adapters/     # Port implementations
│   ├── controllers/  # MCP request handlers
│   ├── schemas/      # Zod validation schemas
│   └── mcp/          # MCP server and tool definitions
├── config/           # Environment validation
├── shared/           # Cross-cutting utilities
└── app.ts            # Entry point

Tool Reference

Technical details for developers integrating with or extending the MCP tools.

query_gemini

Query Google's Gemini AI models for text generation, reasoning, and analysis tasks. The model is configured via the GEMINI_DEFAULT_MODEL environment variable.

Parameters:

History Array Item Schema:

{
  "role": "user" | "model",
  "content": "string"
}

Example Response:

{
  "success": true,
  "data": {
    "response": "Recursion is a programming technique where a function calls itself...",
    "model": "gemini-3-pro-preview",
    "finishReason": "STOP",
    "tokenUsage": {
      "prompt": 12,
      "completion": 150,
      "total": 162
    }
  }
}

list_gemini_models

List popular Gemini AI models that can be configured via the GEMINI_DEFAULT_MODEL environment variable.

Parameters: None

Example Response:

{
  "success": true,
  "data": {
    "count": 4,
    "models": [
      {
        "name": "gemini-3-pro-preview",
        "displayName": "Gemini 3 Pro Preview",
        "description": "Most advanced reasoning model with 1M context - best for complex tasks"
      },
      {
        "name": "gemini-2.5-pro",
        "displayName": "Gemini 2.5 Pro",
        "description": "Capable thinking model for complex reasoning, code, math, and STEM"
      },
      {
        "name": "gemini-2.5-flash",
        "displayName": "Gemini 2.5 Flash",
        "description": "Fast and efficient for most tasks with excellent performance"
      },
      {
        "name": "gemini-2.0-flash",
        "displayName": "Gemini 2.0 Flash",
        "description": "Multimodal model optimized for speed and cost-efficiency"
      }
    ]
  }
}

count_gemini_tokens

Count the number of tokens in a text string for the configured Gemini model.

Parameters:

Example Response:

{
  "success": true,
  "data": {
    "totalTokens": 10,
    "model": "gemini-3-pro-preview"
  }
}

Architecture

This project follows Clean Architecture (Ports and Adapters) principles:

• Domain Layer - Core business logic with zero external dependencies

• Infrastructure Layer - External integrations (Gemini SDK, MCP SDK)

• Strict Dependency Rule - Dependencies always point inward

For detailed architectural documentation, see ARCHITECTURE.md.

Troubleshooting

Claude Code Issues

"Server not found" or tools not appearing

• Verify the MCP server is added: claude mcp list

• Check the path to dist/app.js is absolute and correct

• Ensure the project has been built: npm run build

"GOOGLE_CLOUD_PROJECT is required"

• Verify the project ID is set in the MCP configuration

• Check with: claude mcp list to see environment variables

"Could not load the default credentials" / 401 Unauthorized

• Run gcloud auth application-default login to refresh ADC

• Or set GOOGLE_APPLICATION_CREDENTIALS to a valid service-account JSON key

• Confirm the principal has roles/aiplatform.user on the project

"Permission denied on resource project ..."

• The Vertex AI API may not be enabled. See Enable the API.

• The service account or user lacks roles/aiplatform.user.

Server crashes on startup

• Check Node.js version: node --version (must be 20+)

• Verify dependencies are installed: npm install

API Issues

"Rate limit exceeded"

• Gemini API has rate limits; wait and retry

• Consider using gemini-2.0-flash for higher rate limits

"Content filtered" error

• Gemini has content safety filters

• Rephrase your prompt to avoid triggering filters

Streaming not working

• Streaming is enabled by default

• Set stream: false in your query if needed

Debug Mode

Enable debug logging for troubleshooting:

claude mcp add gemini \
  -e GOOGLE_CLOUD_PROJECT=your-gcp-project-id \
  -e GEMINI_DEFAULT_MODEL=gemini-2.5-pro \
  -e LOG_LEVEL=debug \
  -- node /path/to/dist/app.js

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Create a feature branch: git checkout -b feat/your-feature

3. Make your changes following the code standards in CLAUDE.md

4. Run tests: npm test

5. Run linting: npm run lint

6. Commit with conventional commits: git commit -m "feat: add new feature"

7. Push and create a Pull Request

Code Standards

• TypeScript strict mode required

• All exported functions need explicit return types

• Use neverthrow Result pattern for error handling

• Validate inputs with Zod at boundaries

• 100% test coverage for domain layer

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Claude Code - The CLI tool this server is built for

• Model Context Protocol - The protocol enabling this integration

• Google Gemini - The AI models powering this server