mcp-server-gemini

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

• 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

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

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

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

"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.

• 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

• 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

# 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

Contributions are welcome! Please see our Contributing Guide.

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

• 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

MIT