@mgabr/gemini-mcp-server

v1.0.0

Published

3 months ago

MCP server for Google Gemini CLI integration

0High
0Medium
0Low

mgabr

mcp model-context-protocol gemini claude-code ai llm

Gemini MCP Server

A Model Context Protocol (MCP) server for seamless Google Gemini integration with Claude Code and other MCP-compatible clients.

🚀 Quick Start (OS-Aware Installation)

One-Line Install (Recommended)

# macOS & Linux
npm install -g gemini-mcp-server && gemini-mcp-server --install

# Windows (requires WSL)
wsl -- npm install -g gemini-mcp-server && gemini-mcp-server --install

Platform-Specific Instructions

🍎 macOS (10.15+)

# Install Node.js 18+ if needed
brew install node

# Install Gemini CLI and authenticate
npm install -g @google/gemini-cli
gemini auth

# Install and configure MCP server
npm install -g gemini-mcp-server
node install-mcp.js

🐧 Linux (Ubuntu 20.04+/Debian 10+)

# Install Node.js 18+ if needed
sudo apt update && sudo apt install nodejs npm

# Install Gemini CLI and authenticate  
npm install -g @google/gemini-cli
gemini auth

# Install and configure MCP server
npm install -g gemini-mcp-server
node install-mcp.js

🪟 Windows (WSL Required)

# Install WSL first
wsl --install

# In WSL terminal:
sudo apt update && sudo apt install nodejs npm
npm install -g @google/gemini-cli
gemini auth
npm install -g gemini-mcp-server
node install-mcp.js

Note: Claude Code does NOT run directly on Windows - WSL is required!

📦 Installation Options

Option 1: Global Installation (Recommended)

npm install -g @claude-code/gemini-mcp

Option 2: Local Project Installation

npm install @claude-code/gemini-mcp
npx gemini-mcp setup

Option 3: Direct from GitHub

git clone https://github.com/claude-code/gemini-mcp.git
cd gemini-mcp
npm install
npm run setup

⚡ Claude Code Integration

Auto Configuration

gemini-mcp install

Manual Configuration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "gemini": {
      "command": "gemini-mcp",
      "args": ["start"]
    }
  }
}

🔧 Configuration Options

Basic Configuration

{
  "port": 9222,
  "model": "gemini-2.0-flash-exp",
  "host": "0.0.0.0",
  "agentName": "gemini-mcp-agent"
}

Advanced Configuration

{
  "port": 9222,
  "host": "0.0.0.0",
  "model": "gemini-2.0-flash-exp",
  "agentName": "gemini-mcp-agent",
  "timeout": 60000,
  "maxBuffer": 2097152,
  "enableLogging": true,
  "logLevel": "info",
  "cors": {
    "origin": "*",
    "credentials": true
  },
  "rateLimiting": {
    "enabled": false,
    "maxRequests": 100,
    "windowMs": 60000
  },
  "authentication": {
    "enabled": false,
    "apiKey": null,
    "allowedOrigins": []
  },
  "gemini": {
    "defaultModel": "gemini-2.0-flash-exp",
    "fallbackModel": "gemini-1.5-flash",
    "maxTokens": 4096,
    "temperature": 0.7,
    "customPrompts": {
      "system": "You are a helpful AI assistant integrated via MCP.",
      "prefixes": {
        "code": "Please provide a code solution for: ",
        "explain": "Please explain in detail: ",
        "debug": "Help debug this issue: "
      }
    }
  },
  "features": {
    "codeExecution": false,
    "fileAccess": false,
    "webSearch": false,
    "streaming": false,
    "multiTurn": true,
    "sessionPersistence": true
  },
  "security": {
    "sanitizeInputs": true,
    "validateCommands": true,
    "maxCommandLength": 10000,
    "blockedCommands": ["rm", "del", "format"]
  }
}

Environment Variables

# Override any config option
GEMINI_MCP_PORT=8080
GEMINI_MCP_MODEL=gemini-1.5-pro
GEMINI_MCP_HOST=127.0.0.1
GEMINI_MCP_TIMEOUT=120000

# Gemini API settings
GOOGLE_API_KEY=your_api_key_here
GEMINI_CLI_CONFIG_PATH=/custom/path/.gemini

# Security settings
GEMINI_MCP_API_KEY=your_mcp_api_key
GEMINI_MCP_ALLOWED_ORIGINS=localhost,127.0.0.1

🛠️ CLI Commands

Server Management

gemini-mcp start [options]         # Start server
gemini-mcp stop                    # Stop server  
gemini-mcp restart                 # Restart server
gemini-mcp status                  # Check status

Configuration Management

gemini-mcp config --list           # Show current config
gemini-mcp config --set key=value  # Set config value
gemini-mcp config --get key        # Get config value
gemini-mcp config --reset          # Reset to defaults

Advanced Operations

# Start with custom options
gemini-mcp start --port 8080 --model gemini-1.5-pro --daemon

# Start with specific config file
gemini-mcp start --config /path/to/config.json

# Start with environment override
GEMINI_MCP_PORT=8080 gemini-mcp start

# Enable debug mode
gemini-mcp start --debug --log-level debug

# Production mode with security
gemini-mcp start --production --auth --rate-limit

🔌 API Endpoints

Health Check

GET /health

Agent Information

GET /.well-known/agent.json

MCP Protocol

POST /
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "sendTask",
  "params": {
    "id": "task-123",
    "message": {
      "parts": [{"type": "text", "text": "Hello Gemini!"}]
    }
  },
  "id": "req-1"
}

Configuration API

GET /config                        # Get current config
PUT /config                        # Update config
POST /config/reload                # Reload config
GET /config/schema                 # Get config schema

Admin APIs (when auth enabled)

GET /admin/stats                   # Server statistics
GET /admin/tasks                   # Active tasks
POST /admin/tasks/{id}/cancel      # Cancel task
GET /admin/logs                    # Recent logs
POST /admin/maintenance            # Maintenance mode

🔐 Security Features

API Key Authentication

# Start with API key auth
gemini-mcp start --auth --api-key your_secret_key

# Use in requests
curl -H "Authorization: Bearer your_secret_key" http://localhost:9222/health

Rate Limiting

# Enable rate limiting (100 req/min per IP)
gemini-mcp start --rate-limit --max-requests 100

CORS Configuration

{
  "cors": {
    "origin": ["https://claude.ai", "http://localhost:3000"],
    "credentials": true,
    "maxAge": 86400
  }
}

SSL/TLS Support

# Start with HTTPS
gemini-mcp start --ssl --cert ./cert.pem --key ./key.pem

🚀 Production Deployment

Docker Support

FROM node:18-alpine
COPY . /app
WORKDIR /app
RUN npm install --production
EXPOSE 9222
CMD ["gemini-mcp", "start"]

Systemd Service

[Unit]
Description=Gemini MCP Server
After=network.target

[Service]
Type=simple
User=gemini-mcp
WorkingDirectory=/opt/gemini-mcp
ExecStart=/usr/bin/gemini-mcp start --production
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Nginx Reverse Proxy

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:9222;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🎯 Advanced Use Cases

Multiple Model Support

{
  "models": {
    "fast": "gemini-2.0-flash-exp",
    "pro": "gemini-1.5-pro", 
    "vision": "gemini-pro-vision"
  },
  "routing": {
    "code": "fast",
    "analysis": "pro",
    "image": "vision"
  }
}

Custom Prompt Templates

{
  "promptTemplates": {
    "codeReview": "Please review this code for: ${criteria}. Code: ${code}",
    "documentation": "Generate documentation for: ${code}",
    "testing": "Create tests for this function: ${function}"
  }
}

Integration with CI/CD

# GitHub Actions
- name: Start Gemini MCP
  run: |
    npm install -g @claude-code/gemini-mcp
    gemini-mcp start --daemon --port 9222
    
- name: Run AI-assisted tests
  run: |
    # Your tests that use the MCP server
    npm test

Load Balancing

# Start multiple instances
gemini-mcp start --port 9222 --instance-id server-1
gemini-mcp start --port 9223 --instance-id server-2
gemini-mcp start --port 9224 --instance-id server-3

# Use load balancer config
gemini-mcp start --load-balance --instances 3

📊 Monitoring & Observability

Metrics Endpoint

GET /metrics  # Prometheus-compatible metrics

Logging Configuration

{
  "logging": {
    "level": "info",
    "format": "json",
    "outputs": ["console", "file"],
    "file": {
      "path": "./logs/gemini-mcp.log",
      "maxSize": "100MB",
      "maxFiles": 10
    }
  }
}

Health Checks

# Basic health
curl http://localhost:9222/health

# Detailed health with dependencies
curl http://localhost:9222/health/detailed

# Ready check for load balancers  
curl http://localhost:9222/ready

🐛 Troubleshooting

Common Issues

Gemini CLI not found

npm install -g @google/gemini-cli
gemini auth

Port already in use

gemini-mcp start --port 8080
# or
gemini-mcp config --set port=8080

Authentication failed

gemini auth --reauth

Connection timeout

gemini-mcp config --set timeout=120000

Debug Mode

# Start in debug mode
gemini-mcp start --debug

# View logs
gemini-mcp logs --tail -f

# Check configuration
gemini-mcp config --validate

Support

🐛 Issues: GitHub Issues
💬 Discord: Claude Code Community
📧 Email: [email protected]

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by the Claude Code community