🤖 MCP Server Gemini

License: MIT TypeScript Node.js

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)

npm install -g mcp-server-gemini

Option 2: Local Development

git clone https://github.com/gurr-i/mcp-server-gemini-pro.git cd mcp-server-gemini-pro npm install npm run build

Configuration

1. Set up your API key

Option A: Environment Variable

export GEMINI_API_KEY="your_api_key_here"

Option B: .env file

echo "GEMINI_API_KEY=your_api_key_here" > .env

2. Configure Claude Desktop

Add to your claude_desktop_config.json:

For Global Installation:

{ "mcpServers": { "gemini": { "command": "mcp-server-gemini", "env": { "GEMINI_API_KEY": "your_api_key_here" } } } }

For Local Installation:

{ "mcpServers": { "gemini": { "command": "node", "args": ["/path/to/mcp-server-gemini-pro/dist/enhanced-stdio-server.js"], "env": { "GEMINI_API_KEY": "your_api_key_here" } } } }

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

"Use Gemini to explain quantum computing in simple terms" "Generate a creative story about AI using Gemini 2.5 Pro"

Advanced Features

"Use Gemini with JSON mode to extract key points from this text" "Use Gemini with grounding to get the latest news about AI" "Generate a Python function using Gemini's thinking capabilities"

Image Analysis

"Analyze this image with Gemini" (attach image) "What's in this screenshot using Gemini vision?"

Development Tasks

"Use Gemini to review this code and suggest improvements" "Generate comprehensive tests for this function using Gemini"

⚙️ Configuration

Environment Variables

The server can be configured using environment variables or a .env file:

Required Configuration

# Google AI Studio API Key (required) GEMINI_API_KEY=your_api_key_here

Optional Configuration

# Logging level (default: info) # Options: error, warn, info, debug LOG_LEVEL=info # Enable performance metrics (default: false) ENABLE_METRICS=false # Rate limiting configuration RATE_LIMIT_ENABLED=true # Enable/disable rate limiting (default: true) RATE_LIMIT_REQUESTS=100 # Max requests per window (default: 100) RATE_LIMIT_WINDOW=60000 # Time window in ms (default: 60000 = 1 minute) # Request timeout in milliseconds (default: 30000 = 30 seconds) REQUEST_TIMEOUT=30000 # Environment mode (default: production) NODE_ENV=production

Environment Setup

Development Environment

# .env for development GEMINI_API_KEY=your_api_key_here NODE_ENV=development LOG_LEVEL=debug RATE_LIMIT_ENABLED=false REQUEST_TIMEOUT=60000

Production Environment

# .env for production GEMINI_API_KEY=your_api_key_here NODE_ENV=production LOG_LEVEL=warn RATE_LIMIT_ENABLED=true RATE_LIMIT_REQUESTS=100 RATE_LIMIT_WINDOW=60000 REQUEST_TIMEOUT=30000 ENABLE_METRICS=true

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

{ "mcpServers": { "gemini": { "command": "mcp-server-gemini", "env": { "GEMINI_API_KEY": "your_api_key_here" } } } }

Advanced Configuration

{ "mcpServers": { "gemini": { "command": "mcp-server-gemini", "env": { "GEMINI_API_KEY": "your_api_key_here", "LOG_LEVEL": "info", "RATE_LIMIT_REQUESTS": "200", "REQUEST_TIMEOUT": "45000" } } } }

Local Development Configuration

{ "mcpServers": { "gemini": { "command": "node", "args": ["/path/to/mcp-server-gemini-pro/dist/enhanced-stdio-server.js"], "cwd": "/path/to/mcp-server-gemini-pro", "env": { "GEMINI_API_KEY": "your_api_key_here", "NODE_ENV": "development", "LOG_LEVEL": "debug" } } } }

🛠️ 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

# Clone the repository git clone https://github.com/gurr-i/mcp-server-gemini-pro.git cd mcp-server-gemini-pro # Install dependencies npm install # Set up environment variables cp .env.example .env # Edit .env and add your GEMINI_API_KEY

Available Scripts

Development

npm run dev # Start development server with hot reload npm run dev:watch # Start with file watching (nodemon) npm run build # Build for production npm run build:watch # Build with watch mode npm run clean # Clean build directory

Testing

npm test # Run all tests npm run test:watch # Run tests in watch mode npm run test:coverage # Run tests with coverage report npm run test:integration # Run integration tests (requires API key)

Code Quality

npm run lint # Lint TypeScript code npm run lint:fix # Fix linting issues automatically npm run format # Format code with Prettier npm run format:check # Check code formatting npm run type-check # Run TypeScript type checking npm run validate # Run all quality checks (lint + test + type-check)

Release & Distribution

npm run prepack # Prepare package for publishing npm run release # Build, validate, and publish to npm

Project Structure

mcp-server-gemini/ ├── src/ # Source code │ ├── config/ # Configuration management │ │ └── index.ts # Environment config with Zod validation │ ├── utils/ # Utility modules │ │ ├── logger.ts # Structured logging system │ │ ├── errors.ts # Custom error classes & handling │ │ ├── validation.ts # Input validation with Zod │ │ └── rateLimiter.ts # Rate limiting implementation │ ├── enhanced-stdio-server.ts # Main MCP server implementation │ └── types.ts # TypeScript type definitions ├── tests/ # Test suite │ ├── unit/ # Unit tests │ │ ├── config.test.ts # Configuration tests │ │ ├── validation.test.ts # Validation tests │ │ └── errors.test.ts # Error handling tests │ ├── integration/ # Integration tests │ │ └── gemini-api.test.ts # Real API integration tests │ └── setup.ts # Test setup and utilities ├── docs/ # Documentation │ ├── api.md # API reference │ ├── configuration.md # Configuration guide │ └── troubleshooting.md # Troubleshooting guide ├── scripts/ # Build and utility scripts │ ├── build.sh # Production build script │ ├── dev.sh # Development script │ └── test.sh # Test execution script ├── .github/workflows/ # GitHub Actions CI/CD │ ├── ci.yml # Continuous integration │ └── release.yml # Automated releases ├── dist/ # Built output (generated) ├── coverage/ # Test coverage reports (generated) └── node_modules/ # Dependencies (generated)

🧪 Testing

Test Suite Overview

The project includes comprehensive testing with unit tests, integration tests, and code coverage reporting.

Running Tests

All Tests

npm test # Run all tests (unit tests only by default) npm run test:watch # Run tests in watch mode for development npm run test:coverage # Run tests with coverage report

Unit Tests

npm test -- --testPathPattern=unit # Run only unit tests npm test -- --testNamePattern="config" # Run specific test suites

Integration Tests

Integration tests require a valid GEMINI_API_KEY and make real API calls:

# Set API key and run integration tests GEMINI_API_KEY=your_api_key_here npm run test:integration # Or set in .env file and run npm run test:integration

Test Coverage

npm run test:coverage # Generate coverage report open coverage/lcov-report/index.html # View coverage report (macOS)

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

// tests/unit/example.test.ts import { describe, it, expect, beforeEach, afterEach } from '@jest/globals'; import { YourModule } from '../../src/your-module.js'; describe('YourModule', () => { beforeEach(() => { // Setup before each test }); afterEach(() => { // Cleanup after each test }); it('should do something', () => { // Test implementation expect(result).toBe(expected); }); });

Custom Matchers

The test suite includes custom Jest matchers:

expect(response).toBeValidMCPResponse(); // Validates MCP response format

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

# Build the Docker image docker build -t mcp-server-gemini . # Run the container docker run -d \ --name mcp-server-gemini \ -e GEMINI_API_KEY=your_api_key_here \ -e LOG_LEVEL=info \ mcp-server-gemini

Using Docker Compose

# Create .env file with your API key echo "GEMINI_API_KEY=your_api_key_here" > .env # Start the service docker-compose up -d # View logs docker-compose logs -f # Stop the service docker-compose down

Development with Docker

# Start development environment docker-compose --profile dev up # This mounts source code for live reloading

Environment-Specific Deployments

Production Deployment

# Production build docker build --target production -t mcp-server-gemini:prod . # Run with production settings docker run -d \ --name mcp-server-gemini-prod \ --restart unless-stopped \ -e GEMINI_API_KEY=your_api_key_here \ -e NODE_ENV=production \ -e LOG_LEVEL=warn \ -e RATE_LIMIT_ENABLED=true \ -e ENABLE_METRICS=true \ mcp-server-gemini:prod

Health Checks

# Check container health docker ps docker logs mcp-server-gemini # Manual health check docker exec mcp-server-gemini node -e "console.log('Health check passed')"

🚀 Deployment Options

1. npm Global Installation

# Install globally npm install -g mcp-server-gemini # Run directly GEMINI_API_KEY=your_key mcp-server-gemini

2. Local Installation

# Clone and build git clone https://github.com/gurr-i/mcp-server-gemini-pro.git cd mcp-server-gemini-pro npm install npm run build # Run locally GEMINI_API_KEY=your_key npm start

3. Docker Deployment

# Using Docker Hub (when published) docker run -e GEMINI_API_KEY=your_key mcp-server-gemini-pro:latest # Using local build docker build -t mcp-server-gemini-pro . docker run -e GEMINI_API_KEY=your_key mcp-server-gemini-pro

4. Process Manager (PM2)

# Install PM2 npm install -g pm2 # Create ecosystem file cat > ecosystem.config.js << EOF module.exports = { apps: [{ name: 'mcp-server-gemini', script: './dist/enhanced-stdio-server.js', env: { NODE_ENV: 'production', GEMINI_API_KEY: 'your_api_key_here', LOG_LEVEL: 'info' } }] } EOF # Start with PM2 pm2 start ecosystem.config.js pm2 save pm2 startup

🔧 Troubleshooting

Common Issues

1. Server Won't Start

# Check if API key is set echo $GEMINI_API_KEY # Verify .env file exists and is readable cat .env | grep GEMINI_API_KEY # Check file permissions ls -la .env chmod 600 .env

2. API Key Issues

# Test API key manually curl -H "Content-Type: application/json" \ -d '{"contents":[{"parts":[{"text":"Hello"}]}]}' \ -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=YOUR_API_KEY"

3. Claude Desktop Integration

# Verify config file location (macOS) ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json # Validate JSON syntax cat claude_desktop_config.json | jq . # Check server installation which mcp-server-gemini npm list -g mcp-server-gemini

4. Rate Limiting

# Temporarily disable rate limiting export RATE_LIMIT_ENABLED=false # Increase limits export RATE_LIMIT_REQUESTS=1000 export RATE_LIMIT_WINDOW=60000

Debug Mode

# Enable debug logging export LOG_LEVEL=debug npm run dev # Or for production export LOG_LEVEL=debug npm start

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

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - not tested

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

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

Gemini MCP Server
aliargun
-
security
-
license
-
quality
Model Context Protocol (MCP) server implementation that enables Claude Desktop to interact with Google's Gemini AI models.
Last updated -
226
MIT License
Gemini MCP Server for Claude Desktop
Garblesnarff
A
security
-
license
A
quality
A server that enables Claude Desktop to generate images using Google's Gemini AI models through the Model Context Protocol (MCP).
Last updated -
8
14
14
MIT License
Gemini MCP Server
palolxx
-
security
-
license
-
quality
An 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
Gemini MCP Server
dakrin
-
security
-
license
-
quality
A 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

View all related MCP servers

🤖 MCP Server Gemini

✨ Features

🧠 Latest Gemini Models

🚀 Advanced Capabilities

🛠️ Production Ready

🚀 Quick Start

Prerequisites

Installation

Option 1: Global Installation (Recommended)

Option 2: Local Development

Configuration

1. Set up your API key

2. Configure Claude Desktop

3. Restart Claude Desktop

💡 Usage Examples

Basic Text Generation

Advanced Features

Image Analysis

Development Tasks

⚙️ Configuration

Environment Variables

Required Configuration

Optional Configuration

Environment Setup

Development Environment

Production Environment

Claude Desktop Configuration

Configuration File Locations

Basic Configuration

Advanced Configuration

Local Development Configuration

🛠️ Available Tools

📊 Model Comparison

🔧 Development

Prerequisites

Setup

Available Scripts

Development

Testing

Code Quality

Release & Distribution

Project Structure

🧪 Testing

Test Suite Overview

Running Tests

All Tests

Unit Tests

Integration Tests

Test Coverage

Test Structure

Unit Tests (tests/unit/)

Integration Tests (tests/integration/)

Writing Tests

Test File Structure

Custom Matchers

Test Configuration

🐳 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

Rate Limiting

Unit Tests (`tests/unit/`)

Integration Tests (`tests/integration/`)