# Gemini MCP Server — Product Specification v2.1.0

## Product Information

| Field | Details |
|-------|---------|
| **Product Name** | mcp-server-gemini |
| **npm Package** | `@lkbaba/mcp-server-gemini` |
| **Current Version** | v2.1.0 |
| **Author** | LKbaba |
| **Based On** | aliargun/mcp-server-gemini v4.2.2 |
| **License** | MIT |
| **Repository** | https://github.com/LKbaba/Gemini-mcp |
| **Last Updated** | 2026-07-09 |

---

## 1. Product Overview

mcp-server-gemini is a dedicated MCP (Model Context Protocol) server that exposes Google Gemini AI capabilities to MCP clients such as Claude Code, Cursor, and Windsurf.

**Core Value**:
- Exposes Google Gemini's multimodal analysis, 1M-token context window, and Google Search grounding as MCP tools consumable by any MCP client
- Supports dual-mode authentication: AI Studio API Key (for personal development) and Vertex AI ADC (for production environments)
- 5 highly specialized tools covering image analysis, code review, codebase analysis, creative brainstorming, and real-time web search

**Runtime Model**: Standard stdio MCP server communicating with MCP clients over the JSON-RPC 2.0 protocol.

---

## 2. Tool Suite

### 2.1 Tool Overview

| Tool Name | Function | Default Model |
|-----------|----------|---------------|
| `gemini_multimodal_query` | Image + text multimodal queries | gemini-3.1-pro-preview |
| `gemini_analyze_content` | Code / document / data content analysis | gemini-3.1-pro-preview |
| `gemini_analyze_codebase` | Full codebase analysis (1M-token context) | gemini-3.1-pro-preview |
| `gemini_brainstorm` | Creative brainstorming with pros, cons, and feasibility | gemini-3.1-pro-preview |
| `gemini_search` | Real-time web search with Google Search grounding | gemini-3.5-flash |

All tools support parallel invocation.

---

### 2.2 gemini_multimodal_query

Analyzes image content combined with natural language questions. Supports screenshots, design mockups, charts, and other visual content.

**Input Parameters**:

```typescript
{
  prompt: string,           // Required: question or instruction about the image
  images: string[],         // Required: image file paths or Base64 data URIs
  outputFormat?: 'text' | 'code' | 'json',  // Optional, default: 'text'
  context?: string,         // Optional: additional context
  model?: 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview'
                            // Optional, default: 'gemini-3.1-pro-preview'
}
```

**Required fields**: `prompt`, `images`

**Supported image formats**:
- File paths (automatically read and converted to Base64), e.g. `./images/screenshot.png`
- Base64 data URIs, e.g. `data:image/png;base64,...`
- HTTP/HTTPS URLs are not supported

---

### 2.3 gemini_analyze_content

Analyzes code, documents, or data. Accepts input either as a file path or as inline content. Automatically detects content type and programming language.

**Input Parameters**:

```typescript
{
  content?: string,         // Inline content (mutually exclusive with filePath)
  filePath?: string,        // File path — tool reads the file automatically (mutually exclusive with content)
                            // e.g. './src/utils/parser.ts'
  type?: 'code' | 'document' | 'data' | 'auto',  // Optional, default: 'auto'
  task?: 'summarize' | 'review' | 'explain' | 'optimize' | 'debug',
                            // Optional, default: 'summarize'
  language?: string,        // Optional: programming language (auto-detected when using filePath)
  focus?: string[],         // Optional: areas to focus on, e.g. ['security', 'performance']
  outputFormat?: 'text' | 'json' | 'markdown',  // Optional, default: 'markdown'
  model?: 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview'
                            // Optional, default: 'gemini-3.1-pro-preview'
}
```

**Required fields**: at least one of `content` or `filePath`

**Supports parallel invocation**: multiple files can be analyzed simultaneously.

---

### 2.4 gemini_analyze_codebase

Analyzes an entire codebase using the 1M-token context window. Provides architectural overviews, security findings, performance bottlenecks, and dependency analysis.

**Input Parameters**:

```typescript
{
  // One of three input methods (at least one required)
  directory?: string,       // Directory path — tool reads files automatically
                            // e.g. './src' or 'C:/Project/src'
  filePaths?: string[],     // List of file paths — tool reads them automatically
                            // e.g. ['./src/index.ts', './src/utils.ts']
  files?: Array<{           // Array of file objects with content (backward-compatible)
    path: string,
    content: string
  }>,

  // Used only with directory
  include?: string[],       // Glob include patterns, e.g. ['**/*.ts', '**/*.tsx']
  exclude?: string[],       // Glob exclude patterns, e.g. ['node_modules/**']

  focus?: 'architecture' | 'security' | 'performance' | 'dependencies' | 'patterns',
                            // Optional: analysis focus area
  deepThink?: boolean,      // Optional: enable deep thinking mode, default: false
  thinkingLevel?: 'low' | 'high',  // Optional: thinking depth, default: 'high'
  outputFormat?: 'markdown' | 'json',  // Optional, default: 'markdown'
  model?: 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview'
                            // Optional, default: 'gemini-3.1-pro-preview'
}
```

**Required fields**: at least one of `directory`, `filePaths`, or `files`

---

### 2.5 gemini_brainstorm

Generates creative ideas around a given topic. Each idea includes pros, cons, and a feasibility assessment. Supports loading project context files to produce ideas that are better tailored to the project.

**Input Parameters**:

```typescript
{
  topic: string,            // Required: brainstorming topic
  context?: string,         // Optional: additional background information
  contextFilePath?: string, // Optional: path to a project context file
                            // e.g. 'README.md' or 'PRD.md'
  contextFiles?: string[],  // Optional: paths to multiple context files
                            // e.g. ['./README.md', './docs/architecture.md']
  count?: number,           // Optional: number of ideas to generate, default: 5
  style?: 'innovative' | 'practical' | 'radical',  // Optional: thinking style
  model?: 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview'
                            // Optional, default: 'gemini-3.1-pro-preview'
}
```

**Required fields**: `topic`

---

### 2.6 gemini_search

Performs real-time web searches using Gemini's built-in Google Search grounding capability. Results include source citations and traceable grounding metadata.

**Input Parameters**:

```typescript
{
  query: string,            // Required: search question or query terms
  context?: string,         // Optional: additional context to guide the search
  thinkingLevel?: 'low' | 'high',  // Optional, default: 'high'
                            // low: faster response; high: deeper reasoning
  outputFormat?: 'text' | 'json',  // Optional, default: 'text'
  model?: 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview'
                            // Optional, default: 'gemini-3.5-flash'
}
```

**Required fields**: `query`

**Ideal use cases**: breaking news, up-to-date documentation, live data, and fact-checking. Supports parallel invocation of multiple queries.

---

## 3. Authentication System

v1.4.0 introduces dual-mode authentication with the following detection priority: **Explicit Vertex AI config → Raw JSON auto-detect → AI Studio API Key**.

### 3.1 Mode A: AI Studio API Key

The simplest configuration, suitable for personal development and testing.

**Required environment variable**:

```
GEMINI_API_KEY=<your-api-key>
```

Obtain an API Key from [Google AI Studio](https://aistudio.google.com/).

---

### 3.2 Mode B: Vertex AI ADC

A more secure approach for production environments, authenticating via Google Application Default Credentials. Supports three configuration sub-modes:

#### Sub-mode 1: Explicit environment variables

```
GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=<your-gcp-project-id>
GOOGLE_CLOUD_LOCATION=global              # Optional, default: global (required for Gemini 3.x Preview models)
GOOGLE_APPLICATION_CREDENTIALS=<path-to-sa-key.json>  # Optional if ADC is already configured
GOOGLE_CREDENTIALS_JSON=<entire-json-content>          # Optional alternative to the line above
```

`GOOGLE_CLOUD_PROJECT` is required; all other variables are optional.

#### Sub-mode 2: Inline credentials (auto-detect)

Expand the fields of a service account JSON key file directly as MCP environment variables. The system automatically recognizes this mode by detecting `type=service_account` — no need to set `GOOGLE_GENAI_USE_VERTEXAI`:

```
type=service_account
project_id=<your-project-id>
private_key_id=<key-id>
private_key=<pem-private-key>
client_email=<sa-email>
client_id=<client-id>
auth_uri=https://accounts.google.com/o/oauth2/auth
token_uri=https://oauth2.googleapis.com/token
...
```

#### Sub-mode 3: GOOGLE_CREDENTIALS_JSON

Pass the entire service account JSON file contents as a single string:

```
GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=<your-gcp-project-id>
GOOGLE_CREDENTIALS_JSON={"type":"service_account","project_id":"...","private_key":"..."}
```

---

### 3.3 Windows Slash Fix

Some MCP clients on Windows corrupt `/` to `\` in environment variable values, breaking PEM private keys and URL fields. v1.4.0 includes a built-in automatic fix that safely un-escapes `private_key`, `auth_uri`, `token_uri`, and related fields — no manual intervention required.

---

### 3.4 Temporary File Credential Strategy

When service account JSON is provided via environment variables, the server writes the credentials to a file in the system temp directory (permissions `0600`) and sets `GOOGLE_APPLICATION_CREDENTIALS` to point to it. This is the most reliable way to ensure the `@google/genai` SDK authenticates correctly on Windows.

---

## 4. Model Configuration

### 4.1 Supported Models

| Model ID | Name | Context Window | Max Output | Default For | Status | Notes |
|----------|------|----------------|-----------|-------------|--------|-------|
| `gemini-3.1-pro-preview` | Gemini 3.1 Pro Preview | 1M tokens | 65,536 tokens | 4 primary tools | Preview | **Current default** — enhanced reasoning and agentic capabilities |
| `gemini-3.5-flash` | Gemini 3.5 Flash | 1M tokens | 65,536 tokens | gemini_search | **GA** | v2.1.0: GA flagship Flash; fast, cost-effective ($1.50/$9.00 per 1M tokens) |
| `gemini-3-pro-preview` | Gemini 3.0 Pro Preview | 1M tokens | 65,536 tokens | — | Shut down | Deprecated (retired 2026-03-09); auto-mapped to 3.1-pro-preview |
| `gemini-3-flash-preview` | Gemini 3.0 Flash Preview | 1M tokens | 65,536 tokens | — | Deprecated | v2.1.0: Auto-mapped to gemini-3.5-flash |
| `gemini-2.5-pro` | Gemini 2.5 Pro | 1M tokens | 65,536 tokens | — | Deprecated | v2.1.0: Shutdown 2026-10-16; auto-mapped to gemini-3.5-flash |

### 4.2 Deprecated Model Auto-mapping

To maintain backward compatibility, deprecated models are automatically remapped with a warning at runtime:

```
gemini-3-pro-preview   →  gemini-3.1-pro-preview  (shut down 2026-03-09)
gemini-3-flash-preview →  gemini-3.5-flash         (v2.1.0: GA replacement available)
gemini-2.5-pro         →  gemini-3.5-flash         (v2.1.0: shutdown 2026-10-16)
```

### 4.3 Model Selection Guide

| Use Case | Recommended Model |
|----------|------------------|
| Complex code analysis, architecture review | `gemini-3.1-pro-preview` |
| Image analysis, multimodal tasks | `gemini-3.1-pro-preview` |
| Large codebase analysis | `gemini-3.1-pro-preview` |
| Web search, quick Q&A | `gemini-3.5-flash` |
| Batch processing, cost optimization | `gemini-3.5-flash` |
| Fallback option | `gemini-3.5-flash` |

---

## 5. Configuration Examples

### 5.1 Claude Code (MCP JSON) — AI Studio Mode

```json
{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@lkbaba/mcp-server-gemini"],
      "env": {
        "GEMINI_API_KEY": "AIza..."
      }
    }
  }
}
```

### 5.2 Claude Code (MCP JSON) — Vertex AI Explicit Config

```json
{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@lkbaba/mcp-server-gemini"],
      "env": {
        "GOOGLE_GENAI_USE_VERTEXAI": "true",
        "GOOGLE_CLOUD_PROJECT": "my-project-123",
        "GOOGLE_CLOUD_LOCATION": "global",
        "GOOGLE_CREDENTIALS_JSON": "{\"type\":\"service_account\",\"project_id\":\"my-project-123\",\"private_key\":\"-----BEGIN RSA PRIVATE KEY-----\\n...\"}"
      }
    }
  }
}
```

### 5.3 Claude Code (MCP JSON) — Vertex AI Inline credentials

```json
{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@lkbaba/mcp-server-gemini"],
      "env": {
        "type": "service_account",
        "project_id": "my-project-123",
        "private_key_id": "abc123",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
        "client_email": "my-sa@my-project-123.iam.gserviceaccount.com",
        "client_id": "123456789",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token"
      }
    }
  }
}
```

### 5.4 Proxy Configuration (Optional)

For network environments that require a proxy, add one of the following environment variables:

```json
{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890"
  }
}
```

---

## 6. Technical Architecture

### 6.1 Tech Stack

| Component | Technology |
|-----------|-----------|
| Language | TypeScript 5.x |
| Runtime | Node.js >= 16 |
| AI SDK | @google/genai ^1.46.0 |
| File Glob | fast-glob ^3.3.3 |
| Glob Matching | micromatch ^4.0.8 |
| Proxy Support | undici ^7.16.0 |
| Module System | ESM (`"type": "module"`) |

### 6.2 Project Structure

```
src/
├── server.ts                  # Main entry point; JSON-RPC 2.0 request routing
├── types.ts                   # MCP protocol type definitions
├── config/
│   ├── constants.ts           # Tool names, API settings, error codes, and other constants
│   └── models.ts              # Model definitions, defaults, and deprecation mappings
├── tools/
│   ├── definitions.ts         # MCP schema definitions for all tools
│   ├── index.ts               # Tool handler exports
│   ├── multimodal-query.ts    # gemini_multimodal_query implementation
│   ├── analyze-content.ts     # gemini_analyze_content implementation
│   ├── analyze-codebase.ts    # gemini_analyze_codebase implementation
│   ├── brainstorm.ts          # gemini_brainstorm implementation
│   └── search.ts              # gemini_search implementation
└── utils/
    ├── gemini-client.ts       # GeminiClient wrapper (image processing, etc.)
    ├── gemini-factory.ts      # Auth detection and GoogleGenAI instance creation
    └── error-handler.ts       # Centralized error handling
```

### 6.3 Runtime Flow

1. **Server startup**: authentication mode is determined via `detectAuthConfig()`
2. **Tool invocation**: client sends a `tools/call` JSON-RPC request
3. **Lazy initialization**: the Gemini client is created on the first tool call
4. **Request routing**: `server.ts` dispatches requests to the appropriate handler based on tool name
5. **Model resolution**: `getModelConfig()` applies deprecation mappings and falls back to the default model
6. **Credential handling**: in Vertex AI mode, inline JSON credentials are written to a temp file before the SDK reads them

### 6.4 API Configuration

| Parameter | Value |
|-----------|-------|
| Timeout | 60,000 ms |
| Max Retries | 3 |
| Retry Interval | 1,000 ms |
| Max Image Size | 10 MB |
| MCP Protocol Version | 2024-11-05 |

---

## 7. Version History

| Version | Release Date | Key Changes |
|---------|-------------|-------------|
| **v2.1.0** | 2026-07 | Added gemini-3.5-flash (GA); deprecated gemini-3-flash-preview and gemini-2.5-pro with auto-mapping; search default → gemini-3.5-flash |
| v2.0.0 | 2026-06 | Migrated protocol layer to @modelcontextprotocol/sdk; replaced hand-written JSON-RPC with SDK Server + StdioServerTransport |
| v1.5.1 | 2026-06 | Fixed JSON-RPC notification handling |
| **v1.4.0** | 2026-03 | Introduced Vertex AI dual-mode authentication; Windows slash fix; temporary file credential strategy; added `GOOGLE_CREDENTIALS_JSON` support and raw JSON auto-detection |
| v1.3.1 | 2026-03 | Bug fixes; upgraded @google/genai SDK |
| v1.3.0 | 2026-03 | Migrated to gemini-3.1-pro-preview as the default model; deprecated gemini-3-pro-preview (retired 2026-03-09); added automatic deprecated-model remapping |
| v1.2.0 | 2026-01 | Streamlined to 5 core tools (removed 4 low-usage tools); added `model` parameter to all tools; introduced `gemini_search` |
| v1.1.0 | 2026-01 | Added filesystem access capability (`filePath` parameter) |
| v1.0.1 | 2025-12 | Initial rewrite based on aliargun/mcp-server-gemini v4.2.2; 8 tools |