Gemini MCP Server

Give Claude Code the power of Gemini 3.1

An MCP server that connects Claude Code to Google's Gemini 3.1, unlocking capabilities that complement Claude's strengths.

Why Gemini + Claude?

Philosophy: Claude is the commander, Gemini is the specialist.

Quick Start

Add to your MCP config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Then restart Claude Code.

Authentication

Two authentication modes are supported. The server auto-detects which mode to use based on environment variables.

Option 1: AI Studio API Key (Simplest)

Best for personal development and quick trials.

1. Visit Google AI Studio and create an API key
2. Add to your MCP config:

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@lkbaba/mcp-server-gemini"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Option 2: Vertex AI (Recommended for Production)

More secure, uses Google Cloud IAM authentication.

Prerequisites:

1. A Google Cloud project with Vertex AI API enabled
2. A service account with Vertex AI User role (create one here)

Setup (2 minutes):

1. Create a service account in GCP Console → download JSON key file
2. Open the JSON key file, copy all key-value pairs
3. Paste them into the env section of your MCP config:

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@lkbaba/mcp-server-gemini"],
      "env": {
        "type": "service_account",
        "project_id": "your-project-id",
        "private_key_id": "key-id-here",
        "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEv...\n-----END PRIVATE KEY-----\n",
        "client_email": "your-sa@your-project.iam.gserviceaccount.com",
        "client_id": "123456789",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-sa%40your-project.iam.gserviceaccount.com",
        "universe_domain": "googleapis.com"
      }
    }
  }
}

The server auto-detects service account credentials from env vars — no GOOGLE_GENAI_USE_VERTEXAI or GOOGLE_CLOUD_PROJECT needed. Just paste and go.

Tip: On Windows, the server automatically fixes slash corruption (/ → \) in PEM private keys that some MCP clients introduce.

Advanced options: You can also use GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_CREDENTIALS_JSON, GOOGLE_APPLICATION_CREDENTIALS (file path), or gcloud auth application-default login. See the environment variables reference below.

Paste JSON approach (Option 2 above — simplest for Vertex AI):

Just paste the service account JSON fields directly into env. No extra variables needed — the server auto-detects type: "service_account".

Explicit Vertex AI mode (advanced):

* At least one credential source is needed: GOOGLE_CREDENTIALS_JSON, GOOGLE_APPLICATION_CREDENTIALS, or gcloud ADC.

AI Studio mode:

If both modes are configured, Vertex AI takes priority.

Migration Notice

v2.0.0 (2026-04): The protocol layer has been rewritten on top of the official @modelcontextprotocol/sdk. This fixes a JSON-RPC notifications/initialized spec violation inherited from the upstream fork, which caused strict MCP clients (recent Claude CLI, some VS Code extensions) to drop the connection with MCP error -32000: Connection closed or to silently omit the Gemini tools from the tool list. No user-facing API changes — upgrade is drop-in.

v1.3.0+:

• The default model is now gemini-3.1-pro-preview
• Old model names are automatically mapped (no config changes needed)
• See CHANGELOG.md for details

Tools (5)

Research & Search

Analysis (1M Token Context)

Multimodal

Creative

Model Selection (v1.3.0)

All tools now support an optional model parameter:

Note: gemini-3-pro-preview is deprecated (retired 2026-03-09) and will be automatically mapped to gemini-3.1-pro-preview.

Example: Use the new default model

{
  "name": "gemini_analyze_content",
  "arguments": {
    "filePath": "./src/index.ts",
    "task": "review",
    "model": "gemini-3.1-pro-preview"
  }
}

Usage Examples

Analyze a Large Codebase

"Use Gemini to analyze the ./src directory for architectural patterns and potential issues"

Search for Latest Documentation

"Search for the latest Next.js 15 App Router documentation"

Analyze an Image

"Analyze this architecture diagram and explain the data flow" (attach image)

Brainstorm with Context

"Brainstorm feature ideas based on this project's README.md"

Proxy Configuration

Add proxy environment variable to your config:

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@lkbaba/mcp-server-gemini"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "HTTPS_PROXY": "http://127.0.0.1:7897"
      }
    }
  }
}

Local Development

git clone https://github.com/LKbaba/Gemini-mcp.git
cd Gemini-mcp
npm install
npm run build
export GEMINI_API_KEY="your_api_key_here"
npm start

Project Structure

src/
├── config/
│   ├── models.ts           # Model configurations
│   └── constants.ts        # Global constants
├── tools/
│   ├── definitions.ts      # MCP tool definitions
│   ├── multimodal-query.ts # Multimodal queries
│   ├── analyze-content.ts  # Content analysis
│   ├── analyze-codebase.ts # Codebase analysis
│   ├── brainstorm.ts       # Brainstorming
│   └── search.ts           # Web search
├── utils/
│   ├── gemini-factory.ts   # Dual-mode auth factory (API Key + Vertex AI)
│   ├── gemini-client.ts    # Gemini API client
│   ├── file-reader.ts      # File system access
│   ├── security.ts         # Path validation
│   ├── validators.ts       # Parameter validation
│   └── error-handler.ts    # Error handling
├── types.ts                # Type definitions
└── server.ts               # Main server

Credits

Based on aliargun/mcp-server-gemini

License

MIT