Gemini MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Google Gemini 2.5 Pro, featuring intelligent conversation context management and full compatibility with Claude Code and other MCP clients.

🌟 Features

• 🤖 Gemini 2.5 Pro Integration: Direct access to Google's latest and most capable AI model
• 💬 Conversation Context: Automatic context management across multiple conversation sessions
• 🛠️ Multiple Tools: Chat completion, token counting, and model listing capabilities
• 🔄 Session Persistence: Maintains conversation history during server lifetime
• ⚡ High Performance: Built with TypeScript and modern async patterns
• 🔒 Secure: Environment-based API key management with no hardcoded secrets
• 📚 Well-Documented: Comprehensive documentation and examples

🚀 Quick Start

Installation

npm install -g gemini-mcp-server

Setup

1. Get your Google AI API key from Google AI Studio

2. Set environment variable:

export GEMINI_API_KEY="your-api-key-here"

3. Run the server:

gemini-mcp-server

🔧 Usage

With Claude Code

Add to your Claude Code MCP configuration (~/.config/claude-code/mcp.json):

{
  "mcpServers": {
    "gemini": {
      "command": "gemini-mcp-server",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Then restart Claude Code and use:

# Chat with Gemini
gemini_chat_completion --messages '[{"role": "user", "content": "Hello Gemini!"}]'

# Count tokens
gemini_count_tokens --text "How many tokens does this text contain?"

# List available models
gemini_list_models

Programmatic Usage

import { GeminiClient } from 'gemini-mcp-server';

const client = new GeminiClient();

// Simple chat
const response = await client.chatCompletion({
  model: 'gemini-2.5-pro',
  messages: [
    { role: 'user', content: 'Explain quantum computing briefly' }
  ]
});

console.log(response.choices[0].message.content);

// With context and system instruction
const contextualResponse = await client.chatCompletion({
  model: 'gemini-2.5-pro',
  messages: [
    { role: 'user', content: 'I am learning JavaScript' },
    { role: 'assistant', content: 'Great! JavaScript is a versatile language...' },
    { role: 'user', content: 'What should I learn next?' }
  ],
  systemInstruction: 'You are a helpful programming tutor',
  temperature: 0.7,
  maxTokens: 2048
});

🛠️ Available Tools

gemini_chat_completion

Generate responses using Gemini with conversation context.

Parameters:

• model (optional): Model name (default: gemini-2.5-pro)
• messages: Array of conversation messages
• temperature (optional): Randomness control (0.0-2.0, default: 1.0)
• maxTokens (optional): Maximum response tokens (default: 8192)
• systemInstruction (optional): System prompt to guide behavior
• stream (optional): Stream response (default: false)

Response Format:

{
  "id": "gemini_1703123456_abc123def",
  "object": "chat.completion",
  "created": 1703123456,
  "model": "gemini-2.5-pro",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Response text here..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 25,
    "total_tokens": 35
  }
}

gemini_count_tokens

Count tokens in text using Gemini's tokenizer.

Parameters:

• model (optional): Model for token counting (default: gemini-2.5-pro)
• text: Text to analyze

Response:

{
  "totalTokens": 42
}

gemini_list_models

List available Gemini models and their capabilities.

Response:

[
  {
    "name": "models/gemini-2.5-pro",
    "displayName": "Gemini 2.5 Pro",
    "description": "High-quality model for complex reasoning tasks",
    "inputTokenLimit": 1000000,
    "outputTokenLimit": 8192
  }
]

🧠 Context Management

The server provides intelligent conversation context management:

Automatic Context

• Session Persistence: Context maintained during server lifetime
• Conversation Threads: Multiple independent conversations supported
• Smart Merging: Automatic deduplication and history management
• Memory Efficiency: Optimized in-memory storage

Manual Control

const client = new GeminiClient();

// Get conversation history
const history = client.getConversationHistory(messages);

// Clear specific conversation
client.clearConversationHistory(messages);

// Clear all conversations
client.clearAllConversationHistories();

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│   MCP Server     │───▶│  Gemini API     │
│  (Claude Code)  │    │                  │    │  (Google AI)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │ Context Manager  │
                       │ (In-Memory)      │
                       └──────────────────┘

📝 Examples

Code Review Assistant

const codeReview = await client.chatCompletion({
  messages: [{
    role: 'user',
    content: `Review this TypeScript code:\n\n${codeSnippet}`
  }],
  systemInstruction: 'You are a senior TypeScript developer. Focus on type safety, performance, and best practices.',
  temperature: 0.3
});

Interactive Learning

class LearningBot {
  constructor() {
    this.client = new GeminiClient();
    this.conversation = [];
  }

  async ask(question) {
    this.conversation.push({ role: 'user', content: question });
    
    const response = await this.client.chatCompletion({
      messages: this.conversation,
      systemInstruction: 'You are a patient tutor. Explain concepts clearly with examples.',
      temperature: 0.8
    });
    
    const answer = response.choices[0].message.content;
    this.conversation.push({ role: 'assistant', content: answer });
    
    return answer;
  }
}

// Usage
const tutor = new LearningBot();
console.log(await tutor.ask("What is recursion?"));
console.log(await tutor.ask("Can you give me a simple example?"));
console.log(await tutor.ask("What are the common pitfalls?"));

Documentation Generator

async function generateDocs(apiCode) {
  return await client.chatCompletion({
    messages: [{
      role: 'user',
      content: `Generate comprehensive API documentation:\n\n${apiCode}`
    }],
    systemInstruction: 'Generate clear, professional API documentation with examples, parameters, and return values.',
    maxTokens: 4096,
    temperature: 0.2
  });
}

🔒 Security & Best Practices

Environment Variables

Always use environment variables for API keys:

# .env
GEMINI_API_KEY=your_actual_api_key_here
NODE_ENV=production

Rate Limiting

The server respects Google's API rate limits. For high-volume usage:

// Implement your own rate limiting
const rateLimitedClient = new Proxy(client, {
  get(target, prop) {
    if (prop === 'chatCompletion') {
      return rateLimiter.wrap(target[prop].bind(target));
    }
    return target[prop];
  }
});

Error Handling

try {
  const response = await client.chatCompletion(params);
  return response;
} catch (error) {
  if (error.message.includes('API_KEY')) {
    console.error('Invalid or missing API key');
  } else if (error.message.includes('quota')) {
    console.error('API quota exceeded');
  } else {
    console.error('Unexpected error:', error.message);
  }
  throw error;
}

🚢 Deployment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3000
CMD ["npm", "start"]

Docker Compose

version: '3.8'
services:
  gemini-mcp:
    build: .
    environment:
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - NODE_ENV=production
    ports:
      - "3000:3000"
    restart: unless-stopped

Cloud Deployment

The server works on all major cloud platforms:

• Heroku: git push heroku main
• Railway: Connect your GitHub repository
• Vercel: Deploy as serverless functions
• AWS/GCP/Azure: Use container services

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/your-username/gemini-mcp-server.git
cd gemini-mcp-server
npm install
npm run dev

Running Tests

npm test

Code Style

We use TypeScript with strict mode. Run type checking:

npm run typecheck

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Google AI for the Gemini API
• Anthropic for the Model Context Protocol
• Claude Code community

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 🚀 Model Context Protocol

📊 Roadmap

• [ ] Streaming Support: Real-time response streaming
• [ ] Function Calling: Tool use capabilities
• [ ] Image Input: Multimodal conversation support
• [ ] Persistent Storage: Database-backed context management
• [ ] Load Balancing: Multi-instance deployment support
• [ ] Metrics: Built-in monitoring and analytics

Made with ❤️ for the MCP and Claude Code community