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

Related MCP server: Gemini MCP Server

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

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

   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