MCP Gemini Server

Overview

This project provides a dedicated MCP (Model Context Protocol) server that wraps the @google/genai SDK. It exposes Google's Gemini model capabilities as standard MCP tools, allowing other LLMs (like Claude) or MCP-compatible systems to leverage Gemini's features as a backend workhorse.

This server simplifies integration with Gemini models by providing a consistent, tool-based interface via the MCP standard.

What This Enables

In simple terms, this server lets you:

• Have one AI (like Claude) use another AI (Gemini) for specific tasks
• Access Gemini's capabilities through a standardized interface
• Mix and match AI capabilities without managing multiple complex APIs
• Build more powerful applications that leverage the best features of different AI models

Think of it as creating a universal translator that allows different AI systems to work together seamlessly.

Quick Start

# Clone the repository
git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server

# Create your .env file
cp .env.example .env
# Edit .env with your API key from https://aistudio.google.com/app/apikey

# Install, build and run
npm install
npm run build
npm start

# Health check (in another terminal)
curl http://localhost:3000/health

With Docker:

git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server
cp .env.example .env  # Edit with your API key
docker-compose up -d

Or with Docker:

# Clone and setup
git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server
cp .env.example .env
# Edit .env with your API key

# Run with Docker Compose
docker-compose up -d

# Health check
curl http://localhost:3000/health

Key Features

• Core Generation: Standard (gemini_generateContent) and streaming (gemini_generateContentStream) text generation.
• Function Calling: Enables Gemini models to request the execution of client-defined functions (gemini_functionCall).
• Stateful Chat: Manages conversational context across multiple turns (gemini_startChat, gemini_sendMessage, gemini_sendFunctionResult).
• File Handling: Upload, list, retrieve, and delete files using the Gemini API.
• Caching: Create, list, retrieve, update, and delete cached content to optimize prompts.
• Fallback Mechanisms: Intelligent model fallback system that:
  • Automatically switches to alternative models when quota limits are reached
  • Supports configurable fallback model chains
  • Handles various quota exceeded scenarios gracefully
  • Maintains quality while ensuring service continuity
• Token Management:
  • Configurable token limits per request
  • Automatic token counting for inputs
  • Safeguards against token limit overruns
  • Optimizes context windows for different model versions

Model Fallback System

The server implements a sophisticated fallback mechanism:

1. Primary Model Usage:

   {
     defaultModel: 'gemini-pro',
     fallbackModels: ['gemini-1.5-flash', 'gemini-1.0-pro']
   }
   

2. Fallback Triggers:

   • Quota exceeded errors
   • Rate limit errors
   • Resource exhaustion
   • Model-specific unavailability

3. Fallback Process:

   • Attempts primary model first
   • On quota/rate limit, tries next model in chain
   • Preserves original request parameters
   • Returns success from first available model
   • Throws error only if all models fail

4. Error Detection:

   • Intelligent parsing of error messages
   • Distinguishes between quota and other errors
   • Maintains error context through fallback chain
   • Provides detailed error reporting

Token Management

The server handles tokens intelligently:

1. Input Token Counting:

   • Automatic counting before API calls
   • Respects model-specific limits
   • Handles multi-modal content
   • Preserves token count through fallbacks

2. Context Window Management:

   {
     maxInputTokens: 30720,  // Model-specific
     maxOutputTokens: 2048,  // Configurable
     reserveTokens: 50       // Safety buffer
   }
   

3. Token Optimization:

   • Dynamic context window adjustment
   • Efficient token usage in chat history
   • Automatic truncation when needed
   • Preserves semantic coherence

Prerequisites

• Node.js (v18 or later)
• An API Key from Google AI Studio (https://aistudio.google.com/app/apikey).
  • Important: The File Handling and Caching APIs are only compatible with Google AI Studio API keys and are not supported when using Vertex AI credentials. This server does not currently support Vertex AI authentication.

Installation & Setup

Option 1: Direct Development Setup (Recommended for Active Development)

1. Clone/Place Project:

git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server

2. Install Dependencies:

npm install

3. Configure Environment: Create a .env file in the project root:

# Google Gemini API Key from https://aistudio.google.com/app/apikey
GOOGLE_GEMINI_API_KEY=your_api_key
GOOGLE_GEMINI_MODEL=gemini-pro  # Optional: Set default model

4. Build Project:

npm run build

5. Start the Server:

npm start

Option 2: Docker Setup (Recommended for Development/Testing)

1. Clone and Configure:

git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server

2. Create Environment File: Create a .env file with your API key:

GOOGLE_GEMINI_API_KEY=your_api_key
GOOGLE_GEMINI_MODEL=gemini-pro

3. Run with Docker Compose:

docker-compose up -d

The server will be available on port 3000 with automatic health monitoring and restart capabilities.

Option 3: MCP Client Integration

For integrating with MCP clients like Cline/VSCode or Claude Desktop App:

1. Clone/Place Project: Ensure the mcp-gemini-server project directory is accessible on your system.

2. Install Dependencies: Navigate to the project directory in your terminal and run:

   npm install
   

3. Build Project: Compile the TypeScript source code:

   npm run build
   

   This command uses the TypeScript compiler (tsc) and outputs the JavaScript files to the ./dist directory (as specified by outDir in tsconfig.json). The main server entry point will be dist/server.js.

4. Configure MCP Client: Add the server configuration to your MCP client's settings file (e.g., cline_mcp_settings.json for Cline/VSCode, or claude_desktop_config.json for Claude Desktop App). Replace /path/to/mcp-gemini-server with the actual path on your system and YOUR_API_KEY with your Google AI Studio key.

   {
     "mcpServers": {
       "gemini-server": { // Or your preferred name
         "command": "node",
         "args": ["/path/to/mcp-gemini-server/dist/server.js"], // Path to the compiled server entry point
         "env": {
           "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY",
           "GOOGLE_GEMINI_MODEL": "gemini-1.5-flash" // Optional: Set a default model
         },
         "disabled": false,
         "autoApprove": []
       }
       // ... other servers
     }
   }
   

5. Restart MCP Client: Restart your MCP client application (e.g., VS Code with Cline extension, Claude Desktop App) to load the new server configuration. The MCP client will manage starting and stopping the server process.

Configuration

The server uses environment variables for configuration, passed via the env object in the MCP settings:

• GOOGLE_GEMINI_API_KEY (Required): Your API key obtained from Google AI Studio.
• GOOGLE_GEMINI_MODEL (Optional): Specifies a default Gemini model name (e.g., gemini-1.5-flash, gemini-1.0-pro). If set, tools that require a model name (like gemini_generateContent, gemini_startChat, etc.) will use this default when the modelName parameter is omitted in the tool call. This simplifies client calls when primarily using one model. If this environment variable is not set, the modelName parameter becomes required for those tools. See the Google AI documentation for available model names.

Available Tools

This server provides the following MCP tools. Parameter schemas are defined using Zod for validation and description.

Note on Optional Parameters: Many tools accept complex optional parameters (e.g., generationConfig, safetySettings, toolConfig, history, functionDeclarations, contents). These parameters are typically objects or arrays whose structure mirrors the types defined in the underlying @google/genai SDK. For the exact structure and available fields within these complex parameters, please refer to: 1. The corresponding src/tools/*Params.ts file in this project. 2. The official Google AI JS SDK Documentation.

Core Generation

• gemini_generateContent
  • Description: Generates non-streaming text content from a prompt.
  • Required Params: prompt (string)
  • Optional Params: modelName (string), generationConfig (object), safetySettings (array)
• gemini_generateContentStream
  • Description: Generates text content via streaming. (Note: Current implementation uses a workaround and collects all chunks before returning the full text).
  • Required Params: prompt (string)
  • Optional Params: modelName (string), generationConfig (object), safetySettings (array)

Function Calling

• gemini_functionCall
  • Description: Sends a prompt and function declarations to the model, returning either a text response or a requested function call object (as a JSON string).
  • Required Params: prompt (string), functionDeclarations (array)
  • Optional Params: modelName (string), generationConfig (object), safetySettings (array), toolConfig (object)

Stateful Chat

• gemini_startChat
  • Description: Initiates a new stateful chat session and returns a unique sessionId.\n * Required Params: None
  • Optional Params: modelName (string), history (array), tools (array), generationConfig (object), safetySettings (array)
• gemini_sendMessage
  • Description: Sends a message within an existing chat session.\n * Required Params: sessionId (string), message (string)
  • Optional Params: generationConfig (object), safetySettings (array), tools (array), toolConfig (object)
• gemini_sendFunctionResult
  • Description: Sends the result of a function execution back to a chat session.\n * Required Params: sessionId (string), functionResponses (array)
  • Optional Params: generationConfig (object), safetySettings (array)

File Handling (Google AI Studio Key Required)

• gemini_uploadFile
  • Description: Uploads a file from a local path.\n Required Params: filePath (string - must be an absolute path)\n Optional Params: displayName (string), mimeType (string)
• gemini_listFiles
  • Description: Lists previously uploaded files.\n * Required Params: None
  • Optional Params: pageSize (number), pageToken (string - Note: pageToken may not be reliably returned currently).
• gemini_getFile
  • Description: Retrieves metadata for a specific uploaded file.\n * Required Params: fileName (string - e.g., files/abc123xyz)
• gemini_deleteFile
  • Description: Deletes an uploaded file.\n * Required Params: fileName (string - e.g., files/abc123xyz)

Caching (Google AI Studio Key Required)

• gemini_createCache
  • Description: Creates cached content for compatible models (e.g., gemini-1.5-flash).\n * Required Params: contents (array)
  • Optional Params: modelName (string), displayName (string), systemInstruction (object), ttl (string - e.g., '3600s')
• gemini_listCaches
  • Description: Lists existing cached content.\n * Required Params: None
  • Optional Params: pageSize (number), pageToken (string - Note: pageToken may not be reliably returned currently).
• gemini_getCache
  • Description: Retrieves metadata for specific cached content.\n * Required Params: cacheName (string - e.g., cachedContents/abc123xyz)
• gemini_updateCache
  • Description: Updates metadata (TTL, displayName) for cached content.\n * Required Params: cacheName (string)
  • Optional Params: ttl (string), displayName (string)
• gemini_deleteCache
  • Description: Deletes cached content.\n * Required Params: cacheName (string - e.g., cachedContents/abc123xyz)

Usage Examples

Here are examples of how an MCP client (like Cline) might call these tools using the use_mcp_tool format:

Example 1: Simple Content Generation (Using Default Model)

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Write a short poem about a rubber duck."
    }
  </arguments>
</use_mcp_tool>

Example 2: Content Generation (Specifying Model & Config)

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "modelName": "gemini-1.0-pro",
      "prompt": "Explain the concept of recursion in programming.",
      "generationConfig": {
        "temperature": 0.7,
        "maxOutputTokens": 500
      }
    }
  </arguments>
</use_mcp_tool>

Example 3: Starting and Continuing a Chat

Start Chat:

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_startChat</tool_name>
  <arguments>
    {}
  </arguments>
</use_mcp_tool>

(Assume response contains sessionId: "some-uuid-123")

Send Message:

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_sendMessage</tool_name>
  <arguments>
    {
      "sessionId": "some-uuid-123",
      "message": "Hello! Can you tell me about the Gemini API?"
    }
  </arguments>
</use_mcp_tool>

Example 4: Uploading a File

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_uploadFile</tool_name>
  <arguments>
    {
      "filePath": "C:\\Users\\YourUser\\Documents\\my_document.txt", // IMPORTANT: Use absolute path with escaped backslashes if needed
      "displayName": "My Document"
    }
  </arguments>
</use_mcp_tool>

Error Handling

The server returns structured errors using the MCP standard McpError type:

• code: Error type (e.g., InvalidParams, InternalError, NotFound)
• message: Human-readable description
• details: (Optional) Additional information for troubleshooting

Common Error Scenarios:

Error Type	Cause	Resolution
InternalError	Invalid API key, safety blocks	Check key validity and content safety
InvalidParams	Missing/wrong parameters	Verify required fields and data types
NotFound	File/Cache not found	Confirm resource exists and is accessible
ResourceExhausted	Rate limits exceeded	Use fallback models or implement backoff

Check the message and details fields for specific troubleshooting guidance.

Development

This server follows the standard MCP server structure outlined in the project's .clinerules and internal documentation. Key patterns include:

• Service Layer (src/services): Encapsulates interactions with the @google/genai SDK, keeping it decoupled from MCP specifics.
• Tool Layer (src/tools): Adapts service layer functionality to MCP tools, handling parameter mapping and error translation.
• Zod Schemas (src/tools/*Params.ts): Used extensively for defining tool parameters, providing validation, and generating detailed descriptions crucial for LLM interaction.
• Configuration (src/config): Centralized management via ConfigurationManager.
• Types (src/types): Clear TypeScript definitions.

Development Workflow

1. Local Development:

   • Use npm run dev for hot reloading
   • Run npm test to verify your changes
   • Use npm run lint to maintain code quality

2. Code Quality:

   • Run tests before committing: npm test
   • Ensure linting passes: npm run lint
   • Follow TypeScript best practices

3. Version Control:

   • Create feature branches from main
   • Use meaningful commit messages
   • Keep commits focused and logical

4. Testing Changes:

   • Test with different Gemini models
   • Verify error handling
   • Check API responses

Deployment Options

1. Direct Node.js Deployment:

npm ci --production
npm run build
npm start

2. Docker Deployment:

docker build -t mcp-gemini-server .
docker run -d \
  -e GOOGLE_GEMINI_API_KEY=your_api_key \
  -e GOOGLE_GEMINI_MODEL=gemini-pro \
  -p 3000:3000 \
  mcp-gemini-server

3. Docker Compose (Recommended):

docker-compose up -d

4. Environment Variables for Production:
   • GOOGLE_GEMINI_API_KEY: Required
   • GOOGLE_GEMINI_MODEL: Optional, defaults to gemini-pro
   • PORT: Optional, defaults to 3000
   • NODE_ENV: Set to 'production'

Health Monitoring & Troubleshooting

Health Endpoint: /health provides server status, API configuration, and model availability.

Common Issues:

• Port conflicts: Change port in docker-compose.yml or via PORT env var
• API key issues: Verify in Google AI Studio
• Model availability: Check Google AI status page

Debugging:

• Docker logs: docker logs mcp-gemini-server
• Enable verbose logging: DEBUG=mcp:* environment variable

Known Issues and Limitations

API and Model Limitations

• File Handling & Caching APIs: These features are only supported with Google AI Studio API keys and are not available when using Vertex AI credentials. This is a limitation of the Google Gemini API itself, not our implementation.

• Model Availability: Some models may be temporarily unavailable or have different capabilities. While our fallback system helps mitigate this, certain cutting-edge models might experience:

  • Intermittent availability
  • Varying capabilities across versions
  • Different token limits
  • Region-specific access restrictions

• Content Safety Filters: Google's safety filters may block certain content generation that:

  • Contains harmful content
  • Discusses sensitive topics
  • Contains certain prohibited categories These filters are managed by Google and cannot be fully bypassed.

Implementation Limitations

• Streaming Implementation: The gemini_generateContentStream tool uses a workaround that collects all chunks before returning the full text. True streaming directly to the MCP client is not yet implemented. This means:

  • No incremental text delivery
  • Slower perceived response time
  • Higher memory usage for large responses
  • No ability to cancel in-progress generations

• Pagination Issues: The gemini_listFiles and gemini_listCaches tools may not reliably return nextPageToken due to limitations in iterating the SDK's Pager object. This affects:

  • Listing large collections
  • Traversing all pages
  • Consistent pagination experiences

• File Path Requirements: The gemini_uploadFile tool requires absolute file paths when run from the server environment. This means:

  • No relative paths support
  • Path must be accessible to the server process
  • Docker deployments require volume mapping
  • Path format is OS-dependent

• Function Calling Limitations: Function calling capabilities vary by model and may have:

  • Inconsistent support across models
  • Different parameter handling requirements
  • Varying reliability in complex scenarios
  • Model-specific function definition requirements

Technical Workarounds

1. For Streaming: If you need true streaming:

   • Implement a custom server extension
   • Use WebSockets for real-time updates
   • Consider server-sent events

2. For File Paths: When using Docker:

   docker run -v /local/path:/container/path -e FILE_PATH=/container/path/file.txt ...
   

3. For Pagination: Implement client-side collection:

   // Collect all files in client code
   const allFiles = [];
   let pageToken = undefined;
   do {
     const response = await listFiles({ pageToken, pageSize: 100 });
     allFiles.push(...response.files);
     pageToken = response.nextPageToken;
   } while (pageToken);
   

4. For Model Limitations: Design with graceful degradation:

   • Check model capabilities before use
   • Provide fallback UX for unsupported features
   • Test across multiple models
   • Handle feature unavailability gracefully

We are actively working on addressing these limitations in future releases.