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 | ~/Library/Application Support/Claude/claude_desktop_config.json |
Windows | %APPDATA%\Claude\claude_desktop_config.json |
Linux | ~/.config/Claude/claude_desktop_config.json |
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
🔒 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
This server cannot be installed
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 -191JavaScriptMIT License
- AsecurityAlicenseAqualityA server that enables Claude Desktop to generate images using Google's Gemini AI models through the Model Context Protocol (MCP).Last updated -713JavaScriptMIT 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 -1JavaScript
- -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 -3JavaScript