Gemini MCP Server

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

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 ClientConfig 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" } } } }

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

   Configure in Windsurf's MCP settings following their documentation.

   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

Advanced Examples

📖 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

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