npm package: @mgabr/gemini-mcp-server
Description: MCP server for Google Gemini CLI integration
Author: Claude Code Community
Latest version: 1.0.0

# 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)
```bash
# 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+)
```bash
# 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+)
```bash
# 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)
```bash
# 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)
```bash
npm install -g @claude-code/gemini-mcp
```

### Option 2: Local Project Installation
```bash
npm install @claude-code/gemini-mcp
npx gemini-mcp setup
```

### Option 3: Direct from GitHub
```bash
git clone https://github.com/claude-code/gemini-mcp.git
cd gemini-mcp
npm install
npm run setup
```

## ⚡ Claude Code Integration

### Auto Configuration
```bash
gemini-mcp install
```

### Manual Configuration
Add to your Claude Code MCP settings:
```json
{
  "mcpServers": {
    "gemini": {
      "command": "gemini-mcp",
      "args": ["start"]
    }
  }
}
```

## 🔧 Configuration Options

### Basic Configuration
```json
{
  "port": 9222,
  "model": "gemini-2.0-flash-exp",
  "host": "0.0.0.0",
  "agentName": "gemini-mcp-agent"
}
```

### Advanced Configuration
```json
{
  "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
```bash
# 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
```bash
gemini-mcp start [options]         # Start server
gemini-mcp stop                    # Stop server  
gemini-mcp restart                 # Restart server
gemini-mcp status                  # Check status
```

### Configuration Management
```bash
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
```bash
# 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
```bash
GET /health
```

### Agent Information  
```bash
GET /.well-known/agent.json
```

### MCP Protocol
```bash
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
```bash
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)
```bash
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
```bash
# 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
```bash
# Enable rate limiting (100 req/min per IP)
gemini-mcp start --rate-limit --max-requests 100
```

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

### SSL/TLS Support
```bash
# Start with HTTPS
gemini-mcp start --ssl --cert ./cert.pem --key ./key.pem
```

## 🚀 Production Deployment

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

### Systemd Service
```ini
[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
```nginx
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
```json
{
  "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
```json
{
  "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
```yaml
# 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
```bash
# 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
```bash
GET /metrics  # Prometheus-compatible metrics
```

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

### Health Checks
```bash
# 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

1. **Gemini CLI not found**
```bash
npm install -g @google/gemini-cli
gemini auth
```

2. **Port already in use**
```bash
gemini-mcp start --port 8080
# or
gemini-mcp config --set port=8080
```

3. **Authentication failed**
```bash
gemini auth --reauth
```

4. **Connection timeout**
```bash
gemini-mcp config --set timeout=120000
```

### Debug Mode
```bash
# 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](https://github.com/claude-code/gemini-mcp/issues)
- 💬 Discord: [Claude Code Community](https://discord.gg/claude-code)
- 📧 Email: support@claude-code.com

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Made with ❤️ by the Claude Code community**