gemini-cli-agent-mcp by rodrigolima1910 - MCP Server

Gemini CLI Agent MCP

A powerful Model Context Protocol (MCP) server that acts as a background agent for Claude Code, integrating Google's Gemini CLI to provide advanced AI capabilities, file analysis, sandbox execution, and automated task management.

🚀 Features

🤖 Gemini AI Integration: Direct access to Google's Gemini models through CLI
📁 File Analysis: Analyze large files using @file.ext syntax
🔒 Sandbox Execution: Safe code execution in isolated environments
🛠️ Shell Commands: Execute system commands when needed
⚡ Background Processing: Run tasks asynchronously without blocking Claude Code
📝 Structured Responses: Get organized AI responses for code editing suggestions
🔧 Multiple Tools: Comprehensive set of tools for various automation tasks

📋 Available Tools

Tool	Description	Use Cases
`ask-gemini`	Execute Gemini AI prompts with file analysis support	Code review, large file analysis, general AI queries
`sandbox-test`	Run code safely in Gemini's sandbox environment	Test potentially risky code, validate scripts
`Ping`	Test connectivity and server status	Health checks, debugging
`Help`	Get Gemini CLI help and available options	CLI reference, troubleshooting
`shell-exec`	Execute shell commands directly	System operations, file management

🔧 Prerequisites

Required

Node.js 20+ - Download here
Gemini CLI - Install via npm: npm install -g @google/generative-ai-cli
Claude Code - Download here
Gemini API Key - Get from Google AI Studio

Optional

Docker - For sandbox execution features

📦 Installation

1. Clone and Setup

# Clone the repository
git clone https://github.com/rodrigolima1910/gemini-cli-agent-mcp.git
cd gemini-cli-mcp

# Install dependencies
npm install

# Build the project
npm run build

2. Environment Configuration

# Copy the environment template
cp .env.example .env

# Edit with your settings
nano .env

Environment Variables:

# Required: Your Gemini API key
GEMINI_API_KEY=your_api_key_here

# Optional: Gemini CLI path (default: /usr/bin/gemini)
GEMINI_CLI_PATH=/usr/bin/gemini

# Optional: Default model (default: gemini-2.5-pro)
GEMINI_DEFAULT_MODEL=gemini-2.5-pro

# Optional: Timeout in ms (default: 30000)
GEMINI_TIMEOUT=30000

3. Verify Gemini CLI Installation

# Test Gemini CLI
gemini --version

# Test with API key
GEMINI_API_KEY=your_key_here gemini -p "Hello, what's 2+2?"

🎯 Claude Code Integration

Add to MCP Configuration

Add this configuration to your Claude Code .mcp.json file:

{
  "mcpServers": {
    "gemini-cli-agent": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gemini-cli-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

Locate Your .mcp.json File

macOS/Linux:

# Global config
~/.config/claude-code/.mcp.json

# Project-specific
/your/project/.mcp.json

Windows:

# Global config
%APPDATA%\claude-code\.mcp.json

# Project-specific
C:\your\project\.mcp.json

Restart Claude Code

After adding the configuration:

Save the .mcp.json file
Restart Claude Code completely
Verify the MCP is loaded by checking available tools

💡 Usage Examples

Basic AI Queries

// Ask simple questions
await askGemini("What's the best practice for error handling in Node.js?");

// Get code explanations
await askGemini("Explain this regex pattern: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/");

File Analysis

// Analyze a specific file
await askGemini("@src/database/models/user.js Explain this database model and suggest improvements");

// Compare multiple files
await askGemini("@package.json @src/app.js Analyze the dependencies and suggest optimizations");

// Code review
await askGemini("@src/api/routes/auth.js Review this authentication code for security issues");

Sandbox Testing

// Test Python scripts safely
await sandboxTest("Create a Python script that calculates prime numbers up to 1000");

// Validate code changes
await sandboxTest("@my-script.py Run this script and explain what it does");

// Test new algorithms
await sandboxTest("Implement and test a binary search algorithm in JavaScript");

Structured Code Changes

// Get structured edit suggestions
await askGemini("Refactor this function to use async/await", {
  changeMode: true
});

// Architecture improvements
await askGemini("@src/services/ Analyze these services and suggest a better architecture", {
  changeMode: true
});

Shell Operations

// System operations
await shellExec("ls -la /var/log");

// File management
await shellExec("find . -name '*.log' -mtime +7 -delete");

// Git operations
await shellExec("git status && git log --oneline -10");

🎨 Advanced Configuration

Custom Model Selection

// Use different models for different tasks
await askGemini("Complex analysis task", { 
  model: "gemini-2.5-pro" 
});

await askGemini("Quick question", { 
  model: "gemini-2.5-flash" 
});

Sandbox Configuration

// Enable sandbox for risky operations
await sandboxTest("Test this potentially dangerous script", {
  model: "gemini-2.5-pro"
});

Timeout Management

# Increase timeout for complex operations
GEMINI_TIMEOUT=60000 node dist/index.js

🔍 Troubleshooting

Common Issues

❌ "Gemini CLI not found"

# Install Gemini CLI globally
npm install -g @google/generative-ai-cli

# Or specify custom path
export GEMINI_CLI_PATH=/path/to/gemini

❌ "API key invalid"

# Verify your API key
GEMINI_API_KEY=your_key gemini -p "test"

# Check key format (should start with 'AIza')
echo $GEMINI_API_KEY

❌ "MCP server not loading"

Check .mcp.json syntax
Verify absolute paths
Restart Claude Code completely
Check Claude Code logs

❌ "Sandbox not working"

# Install Docker for sandbox features
docker --version

# Pull required image
docker pull us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:latest

Debug Mode

# Enable debug logging
DEBUG=* node dist/index.js

# Test MCP connection
node dist/index.js < test-input.json

Log Analysis

# Check Claude Code logs
tail -f ~/.config/claude-code/logs/mcp.log

# Test MCP manually
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

🏗️ Architecture

gemini-cli-mcp/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── services/
│   │   └── gemini-client.ts   # Gemini CLI integration
│   └── types/
│       └── index.ts          # TypeScript definitions
├── dist/                     # Compiled JavaScript
├── .env.example              # Environment template
├── .gitignore               # Git ignore rules
├── package.json             # Dependencies and scripts
└── tsconfig.json            # TypeScript configuration

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

# Clone and setup
git clone https://github.com/rodrigolima1910/gemini-cli-agent-mcp.git
cd gemini-cli-mcp
npm install

# Development mode
npm run dev

# Run tests
npm test

# Build production
npm run build

Code Standards

TypeScript for type safety
ESLint for code quality
Prettier for formatting
Conventional Commits for commit messages

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

Google for the Gemini AI platform and CLI tools
Anthropic for Claude Code and MCP specifications
Whatsmeow community for inspiration from similar integration patterns
Open Source Community for TypeScript and Node.js ecosystem

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

🗺️ Roadmap

Enhanced Memory Management - Advanced context persistence
File Injection Tools - Advanced file content management
Chat Session Management - Save/resume conversation states
WebSocket Support - Real-time communication
Plugin System - Extensible tool architecture
Performance Optimization - Faster response times
Multi-language Support - Additional CLI integrations

Made with ❤️ for the Claude Code community

Transform your development workflow with the power of Gemini AI and MCP integration!