Provides integration with Google's Gemini AI models, offering access to Gemini 2.5 Pro, 2.5 Flash, and other Gemini series models with capabilities including text generation, image analysis, and Google Search grounding for real-time web information.
๐ค MCP Server Gemini
A state-of-the-art Model Context Protocol (MCP) server that provides seamless integration with Google's Gemini AI models. This server enables Claude Desktop and other MCP-compatible clients to leverage the full power of Gemini's advanced AI capabilities.
โจ Features
๐ง Latest Gemini Models
Gemini 2.5 Pro - Most capable thinking model for complex reasoning
Gemini 2.5 Flash - Fast thinking model with best price/performance
Gemini 2.0 Series - Latest generation models with advanced features
Gemini 1.5 Series - Proven, reliable models for production use
๐ Advanced Capabilities
๐ง Thinking Models - Gemini 2.5 series with step-by-step reasoning
๐ Google Search Grounding - Real-time web information integration
๐ JSON Mode - Structured output with schema validation
๐ฏ System Instructions - Behavior customization and control
๐๏ธ Vision Support - Image analysis and multimodal capabilities
๐ฌ Conversation Memory - Context preservation across interactions
๐ ๏ธ Production Ready
TypeScript - Full type safety and modern development
Comprehensive Error Handling - Robust error management and recovery
Rate Limiting - Built-in protection against API abuse
Detailed Logging - Comprehensive monitoring and debugging
Input Validation - Secure parameter validation with Zod
Retry Logic - Automatic retry with exponential backoff
๐ Quick Start
Prerequisites
Node.js 16+ (Download)
Google AI Studio API Key (Get one here)
Installation
Option 1: Global Installation (Recommended)
Option 2: Local Development
Configuration
1. Set up your API key
Option A: Environment Variable
Option B: .env file
2. Configure Claude Desktop
Add to your claude_desktop_config.json
:
For Global Installation:
For Local Installation:
3. Restart Claude Desktop
Close and restart Claude Desktop completely for changes to take effect.
๐ก Usage Examples
Once configured, you can use Gemini through Claude Desktop with natural language:
Basic Text Generation
Advanced Features
Image Analysis
Development Tasks
โ๏ธ Configuration
Environment Variables
The server can be configured using environment variables or a .env
file:
Required Configuration
Optional Configuration
Environment Setup
Development Environment
Production Environment
Claude Desktop Configuration
Configuration File Locations
OS | Path |
macOS |
|
Windows |
|
Linux |
|
Basic Configuration
Advanced Configuration
Local Development Configuration
๐ ๏ธ Available Tools
Tool | Description | Key Features |
generate_text | Generate text with advanced features | Thinking models, JSON mode, grounding |
analyze_image | Analyze images using vision models | Multi-modal understanding, detailed analysis |
count_tokens | Count tokens for cost estimation | Accurate token counting for all models |
list_models | List all available Gemini models | Real-time model availability and features |
embed_text | Generate text embeddings | High-quality vector representations |
get_help | Get usage help and documentation | Self-documenting with examples |
๐ Model Comparison
Model | Context Window | Features | Best For | Speed |
gemini-2.5-pro | 2M tokens | Thinking, JSON, Grounding | Complex reasoning, coding | Slower |
gemini-2.5-flash โญ | 1M tokens | Thinking, JSON, Grounding | General purpose | Fast |
gemini-2.5-flash-lite | 1M tokens | Thinking, JSON | High-throughput tasks | Fastest |
gemini-2.0-flash | 1M tokens | JSON, Grounding | Standard tasks | Fast |
gemini-2.0-flash-lite | 1M tokens | JSON | Simple tasks | Fastest |
gemini-2.0-pro-experimental | 2M tokens | JSON, Grounding | Experimental features | Medium |
gemini-1.5-pro | 2M tokens | JSON | Legacy support | Medium |
gemini-1.5-flash | 1M tokens | JSON | Legacy support | Fast |
๐ง Development
Prerequisites
Node.js 16+ (Download)
npm 7+ (comes with Node.js)
Git for version control
Google AI Studio API Key (Get one here)
Setup
Available Scripts
Development
Testing
Code Quality
Release & Distribution
Project Structure
๐งช Testing
Test Suite Overview
The project includes comprehensive testing with unit tests, integration tests, and code coverage reporting.
Running Tests
All Tests
Unit Tests
Integration Tests
Integration tests require a valid GEMINI_API_KEY
and make real API calls:
Test Coverage
Test Structure
Unit Tests (tests/unit/
)
Configuration Tests: Environment variable validation, config loading
Validation Tests: Input validation, schema validation, sanitization
Error Handling Tests: Custom error classes, error recovery, retry logic
Utility Tests: Logger, rate limiter, helper functions
Integration Tests (tests/integration/
)
Gemini API Tests: Real API calls to test connectivity and functionality
Model Testing: Verify all supported models work correctly
Feature Testing: JSON mode, grounding, embeddings, token counting
Writing Tests
Test File Structure
Custom Matchers
The test suite includes custom Jest matchers:
Test Configuration
Tests are configured in jest.config.js
with:
TypeScript Support: Full ES modules and TypeScript compilation
Coverage Thresholds: Minimum 70% coverage required
Test Timeout: 30 seconds for integration tests
Setup Files: Automatic test environment setup
๐ณ Docker Deployment
Using Docker
Build and Run
Using Docker Compose
Development with Docker
Environment-Specific Deployments
Production Deployment
Health Checks
๐ Deployment Options
1. npm Global Installation
2. Local Installation
3. Docker Deployment
4. Process Manager (PM2)
๐ง Troubleshooting
Common Issues
1. Server Won't Start
2. API Key Issues
3. Claude Desktop Integration
4. Rate Limiting
Debug Mode
Getting Help
๐ Report Issues
๐ฌ Discussions
๐ Documentation
๐ Security
API Key Security
Never commit API keys to version control
Use environment variables or secure secret management
Rotate keys regularly for production use
Use different keys for development and production
Rate Limiting
Enable rate limiting in production (
RATE_LIMIT_ENABLED=true
)Configure appropriate limits based on your usage patterns
Monitor API usage to prevent quota exhaustion
Input Validation
All inputs are automatically validated and sanitized
XSS and injection protection built-in
Schema validation for all tool parameters
Container Security
Runs as non-root user in Docker
Read-only filesystem with minimal privileges
Security scanning in CI/CD pipeline
๐ Documentation
๐ค Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Workflow
Fork the repository
Create a feature branch
Make your changes
Add tests
Run
npm run validate
Submit a pull request
๐ License
MIT License - see LICENSE file for details.
๐ Acknowledgments
Google AI for the Gemini API
Anthropic for the Model Context Protocol
The open-source community for inspiration and feedback
๐ Support
๐ Report Issues
๐ฌ Discussions
๐ง Email Support
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Model Context Protocol server that enables Claude Desktop and other MCP-compatible clients to leverage Google's Gemini AI models with features like thinking models, Google Search grounding, JSON mode, and vision support.
Related MCP Servers
- -securityAlicense-qualityModel Context Protocol (MCP) server implementation that enables Claude Desktop to interact with Google's Gemini AI models.Last updated -226MIT License
- AsecurityAlicenseAqualityA server that enables Claude Desktop to generate images using Google's Gemini AI models through the Model Context Protocol (MCP).Last updated -81714MIT License
- -security-license-qualityAn MCP server implementation that allows using Google's Gemini AI models (specifically Gemini 1.5 Pro) through Claude or other MCP clients via the Model Context Protocol.Last updated -1
- -securityFlicense-qualityA Model Context Protocol server that enables Claude Desktop to interact with Google's Gemini 2.5 Pro Experimental AI model, with features like Google Search integration and token usage reporting.Last updated -3