# Gemini MCP Server [![smithery badge](https://smithery.ai/badge/mcp-server-gemini)](https://smithery.ai/server/mcp-server-gemini) [![npm version](https://img.shields.io/npm/v/mcp-server-gemini)](https://www.npmjs.com/package/mcp-server-gemini) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/) [![MCP Version](https://img.shields.io/badge/MCP-2024--11--05-green)](https://modelcontextprotocol.io/) 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](https://makersuite.google.com/app/apikey) - 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` ```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: ```json { "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: ```json { "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](USAGE_GUIDE.md)** 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](USAGE_GUIDE.md)** - Complete guide on using all tools and features - **[Parameters Reference](PARAMETERS_REFERENCE.md)** - Detailed documentation of all parameters - **[Quick Reference](QUICK_REFERENCE.md)** - Quick commands cheat sheet - **[Enhanced Features](ENHANCED_FEATURES.md)** - Detailed list of v4.0.0 capabilities - [Claude Desktop Setup Guide](docs/claude-desktop-setup.md) - Detailed setup instructions - [Examples and Usage](docs/examples.md) - Usage examples and advanced configuration - [Implementation Notes](docs/implementation-notes.md) - Technical implementation details - [Development Guide](docs/development-guide.md) - Guide for developers - [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions ## Local Development ```bash # 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](CONTRIBUTING.md). ## 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](docs/troubleshooting.md) 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](docs/claude-desktop-setup.md) ## 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