mcp-server-gemini

Gemini MCP Server

A powerful MCP (Model Context Protocol) server that brings Google's latest Gemini AI models to your favorite development environment. Access Gemini 2.5's thinking capabilities, vision analysis, embeddings, and more through a seamless integration.

🚀 Works with: Claude Desktop, Cursor, Windsurf, and any MCP-compatible client
🎯 Why use this: Get Gemini's cutting-edge AI features directly in your IDE with full parameter control
📚 Self-documenting: Built-in help system means you never need to leave your editor

Features

• 6 Powerful Tools: Text generation, image analysis, token counting, model listing, embeddings, and self-documenting help
• Latest Gemini Models: Support for Gemini 2.5 series with thinking capabilities
• Advanced Features: JSON mode, Google Search grounding, system instructions, conversation memory
• Full MCP Protocol: Standard stdio communication for seamless integration with any MCP client
• Self-Documenting: Built-in help system - no external docs needed
• TypeScript & ESM: Modern, type-safe implementation

Supported Models

Model	Context	Features	Best For
gemini-2.5-pro	2M tokens	Thinking, JSON, Grounding	Complex reasoning
gemini-2.5-flash ⭐	1M tokens	Thinking, JSON, Grounding	General use
gemini-2.5-flash-lite	1M tokens	Thinking, JSON	Fast responses
gemini-2.0-flash	1M tokens	JSON, Grounding	Standard tasks
gemini-1.5-pro	2M tokens	JSON	Legacy support

Quick Start

1. Get Gemini API Key

   • Visit Google AI Studio
   • Create a new API key
   • IMPORTANT: Keep your API key secure and never commit it to version control

2. Configure Your MCP Client

   Claude Desktop

   Config location:

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

   {
     "mcpServers": {
       "gemini": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "github:aliargun/mcp-server-gemini"],
         "env": {
           "GEMINI_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

   Cursor

   Add to Cursor's MCP settings:

   {
     "gemini": {
       "type": "stdio",
       "command": "npx",
       "args": ["-y", "github:aliargun/mcp-server-gemini"],
       "env": {
         "GEMINI_API_KEY": "your_api_key_here"
       }
     }
   }
   

   Windsurf

   Configure in Windsurf's MCP settings following their documentation.

   Other MCP Clients

   Use the standard MCP stdio configuration:

   {
     "type": "stdio",
     "command": "npx",
     "args": ["-y", "github:aliargun/mcp-server-gemini"],
     "env": {
       "GEMINI_API_KEY": "your_api_key_here"
     }
   }
   

3. Restart Your MCP Client

How to Use

Once configured, you can use natural language in your MCP client to access Gemini's capabilities:

Basic Commands

"Use Gemini to explain quantum computing"
"Analyze this image with Gemini" 
"List all Gemini models"
"Get help on using Gemini"

Advanced Examples

"Use Gemini 2.5 Pro with temperature 0.3 to review this code"
"Use Gemini in JSON mode to extract key points with schema {title, summary, tags}"
"Use Gemini with grounding to research the latest in quantum computing"

📖 See the complete Usage Guide for detailed examples and advanced features.

Why Gemini MCP Server?

• Access Latest Models: Use Gemini 2.5 with thinking capabilities - Google's most advanced models
• Full Feature Set: All Gemini API features including JSON mode, grounding, and system instructions
• Easy Setup: One-line npx installation, no complex configuration needed
• Production Ready: Comprehensive error handling, TypeScript types, and extensive documentation
• Active Development: Regular updates with new Gemini features as they're released

Documentation

• Usage Guide - Complete guide on using all tools and features
• Parameters Reference - Detailed documentation of all parameters
• Quick Reference - Quick commands cheat sheet
• Enhanced Features - Detailed list of v4.0.0 capabilities
• Claude Desktop Setup Guide - Detailed setup instructions
• Examples and Usage - Usage examples and advanced configuration
• Implementation Notes - Technical implementation details
• Development Guide - Guide for developers
• Troubleshooting Guide - Common issues and solutions

Local Development

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

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# Start development server
npm run dev

Contributing

Contributions are welcome! Please see our Contributing Guide.

Common Issues

1. Connection Issues

   • Ensure your MCP client is properly restarted
   • Check the client's logs (e.g., ~/Library/Logs/Claude/mcp-server-gemini.log for Claude Desktop on Mac)
   • Verify internet connection
   • See Troubleshooting Guide

2. API Key Problems

   • Verify API key is correct
   • Check API key has proper permissions
   • Ensure the key is set in the environment variable
   • See Setup Guide

Security

• API keys are handled via environment variables only
• Never commit API keys to version control
• The .claude/ directory is excluded from git
• No sensitive data is logged or stored
• Regular security updates
• If your API key is exposed, regenerate it immediately in Google Cloud Console

License

MIT