Gemini MCP Server

Gemini MCP Server

What is Gemini MCP Server about?

Gemini MCP Server acts as a bridge between Claude Code and Google Gemini 3.1. It exposes Gemini’s 1 M‑token context, Google Search grounding, and multimodal vision capabilities as MCP tools, allowing Claude to delegate specialised tasks such as codebase analysis, web‑search‑backed research, image interpretation, and brainstorming.

How to use Gemini MCP Server?

1. Add the server to Claude’s MCP config
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
2. Choose an authentication mode
   • AI Studio API Key – set GEMINI_API_KEY in the env section.
   • Vertex AI Service Account – paste the whole service‑account JSON fields into env. The server auto‑detects this mode.
3. Restart Claude Code – the new "gemini" server becomes available.
4. Invoke tools via Claude prompts, e.g. gemini_analyze_codebase, gemini_search, gemini_multimodal_query, etc.

Key features of Gemini MCP Server

• 1 M token context for whole‑project code analysis.
• Google Search grounding to fetch up‑to‑date documentation and news.
• Multimodal vision: analyse screenshots, diagrams, and designs.
• Dual‑mode authentication – simple API‑key or secure Vertex AI service‑account.
• Model selection per request (gemini-3.1-pro-preview default, gemini-3-flash-preview fast).
• Proxy support via HTTPS_PROXY.
• Built‑in tools:
  • gemini_search
  • gemini_analyze_codebase
  • gemini_analyze_content
  • gemini_multimodal_query
  • gemini_brainstorm

Use cases of Gemini MCP Server

• Large codebase review – run a single prompt to detect architectural patterns or security issues across an entire repository.
• Live documentation lookup – ask Claude for the latest framework docs; Gemini fetches the current web results.
• Design critique – attach an architecture diagram image and receive a textual explanation of data flow.
• Feature brainstorming – provide a README or PRD and generate new feature ideas grounded in the existing project context.
• Fast prototyping – use the flash model for quick look‑ups while relying on the pro model for deep reasoning.

FAQ

Q: Which authentication method should I use? A: For quick experiments, set GEMINI_API_KEY. For production or team environments, use a Vertex AI service‑account JSON for better security and quota management.

Q: Do I need to set any additional Google env variables? A: No. The server auto‑detects service‑account fields from env. Only GEMINI_API_KEY is required for AI‑Studio mode.

Q: How do I change the default model? A: Include a model parameter in the tool arguments, e.g. { "model": "gemini-3-flash-preview" }.

Q: Can I run the server behind a corporate proxy? A: Yes. Add HTTPS_PROXY (or HTTP_PROXY) to the env section of the MCP config.

Q: What if both API‑key and service‑account are provided? A: Vertex AI mode takes precedence.

Q: Is the server compatible with other Claude plugins? A: It follows the standard MCP interface, so any Claude client that supports MCP can load it.

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?

Gemini's Strengths	Use Case
1M Token Context	Analyze entire codebases in one shot
Google Search Grounding	Get real-time documentation & latest info
Multimodal Vision	Understand screenshots, diagrams, designs

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):

Variable	Required	Description
GOOGLE_GENAI_USE_VERTEXAI	Yes	Set to "true" to enable
GOOGLE_CLOUD_PROJECT	Yes	GCP project ID
GOOGLE_CLOUD_LOCATION	No	Region (default: global)
GOOGLE_CREDENTIALS_JSON	No*	Entire service account JSON as a single string
GOOGLE_APPLICATION_CREDENTIALS	No*	File path to service account JSON key

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

AI Studio mode:

Variable	Required	Description
GEMINI_API_KEY	Yes	API key from Google AI Studio

If both modes are configured, Vertex AI takes priority.

Migration Notice (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

Tool	Description
gemini_search	Web search with Google Search grounding. Get real-time info, latest docs, current events.

Analysis (1M Token Context)

Tool	Description
gemini_analyze_codebase	Analyze entire projects with 1M token context. Supports directory path, file paths, or direct content.
gemini_analyze_content	Analyze code, documents, or data. Supports file path or direct content input.

Multimodal

Tool	Description
gemini_multimodal_query	Analyze images with natural language. Understand designs, diagrams, screenshots.

Creative

Tool	Description
gemini_brainstorm	Generate creative ideas with project context. Supports reading README, PRD files.

Model Selection (v1.3.0)

All tools now support an optional model parameter:

Model	Speed	Best For
gemini-3.1-pro-preview	Standard	Complex analysis, deep reasoning, agentic workflows (default)
gemini-3-flash-preview	Fast	Simple tasks, quick responses, search queries

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