Gemini CLI MCP Server

A Model Context Protocol (MCP) server and CLI wrapper for Google's Gemini CLI with OAuth authentication support. This allows you to use Gemini through Claude Desktop/Code without needing API keys - just login with your Google account.

Features

• OAuth Authentication: Login with your Google account, no API keys required
• MCP Server: Full integration with Claude Desktop and Claude Code
• CLI Tool: Command-line interface for direct usage
• Multi-Model Support: Use different Gemini models (gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite)
• File Analysis: Analyze code and documents with context
• Session Persistence: Maintains authentication across sessions
• Headless Mode: Support for environments without browser access

Installation

npm install -g @jacob/gemini-cli-mcp

Prerequisites

You need to have Google's Gemini CLI installed:

# Install globally
npm install -g @google/gemini-cli

# Or use npx
npx @google/gemini-cli

The Gemini CLI provides 60 requests/minute and 1,000 requests/day with a personal Google account.

Quick Start

1. Initial Authentication

# The Gemini CLI handles authentication automatically on first use
# Just run any command and it will prompt for auth if needed
gemini-mcp query "Hello"

# Check authentication status
gemini-mcp auth-status

2. CLI Usage

# Send a query
gemini-mcp query "Explain quantum computing in simple terms"

# Query with specific model (defaults to 2.5-pro)
gemini-mcp query "Write a Python function for binary search" --model gemini-2.5-flash

# Analyze files
gemini-mcp analyze --files src/main.ts src/utils.ts --instruction "Find potential bugs"

# Query with context files
gemini-mcp query "Explain this code" --context main.py utils.py

3. MCP Server Configuration

Add to your Claude Desktop or Claude Code configuration:

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@jacob/gemini-cli-mcp"],
      "env": {
        "GEMINI_MODEL": "gemini-2.5-pro",
        "GEMINI_TIMEOUT": "30000",
        "GEMINI_AUTO_LOGIN": "true",
        "GEMINI_THINKING_ENABLED": "true"
      }
    }
  }
}

Available MCP Tools

gemini_query

Query Gemini with a prompt and optional context files.

{
  prompt: string;          // Your question or prompt
  model?: string;          // Optional: "gemini-2.5-pro" (default), "gemini-2.5-flash", or "gemini-2.5-flash-lite"
  context?: string[];      // Optional: Array of file paths for context
}

gemini_analyze

Analyze files with specific instructions.

{
  files: string[];         // Files to analyze
  instruction: string;     // Analysis instruction
  model?: string;          // Optional: Model to use
}

gemini_auth_status

Check current authentication status.

gemini_login

Initiate authentication flow.

{
  headless?: boolean;      // Show URL instead of opening browser
  account?: string;        // Specific Google account to use
}

gemini_list_models

List available Gemini models.

CLI Commands

Authentication Commands

# Login
gemini-mcp login [options]
  --headless              # Display URL instead of opening browser
  --account <email>       # Specify Google account

# Logout
gemini-mcp logout

# Check auth status
gemini-mcp auth-status

Query Commands

# Send query
gemini-mcp query <prompt> [options]
  -m, --model <model>     # Model to use
  -c, --context <files>   # Context files
  -t, --timeout <ms>      # Timeout in milliseconds

# Analyze files
gemini-mcp analyze [options]
  -f, --files <files>     # Files to analyze (required)
  -i, --instruction <text> # Analysis instruction (required)
  -m, --model <model>     # Model to use

Configuration

# Set configuration
gemini-mcp config --set key=value

# Get configuration
gemini-mcp config --get key

# List all configuration
gemini-mcp config --list

Configuration options:

• model: Default model (gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite)
• timeout: Request timeout in milliseconds
• headlessDefault: Default to headless authentication
• autoLogin: Automatically login if not authenticated
• thinkingEnabled: Enable thinking mode by default (shows model's reasoning)
• thinkingBudget: Default token budget for thinking process

Environment Variables

• GEMINI_MODEL: Default model to use (gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite)
• GEMINI_TIMEOUT: Request timeout (ms)
• GEMINI_AUTH_CACHE: Authentication cache directory
• GEMINI_HEADLESS: Default to headless mode
• GEMINI_AUTO_LOGIN: Auto-login on first use
• GEMINI_THINKING_ENABLED: Enable thinking mode by default
• GEMINI_THINKING_BUDGET: Default thinking token budget

Examples

Example 1: Code Review

# Analyze a TypeScript project for issues
gemini-mcp analyze \
  --files "src/**/*.ts" \
  --instruction "Review this code for potential bugs, security issues, and suggest improvements"

Example 2: Documentation Generation

# Generate documentation for a module with thinking mode
gemini-mcp query "Generate comprehensive JSDoc documentation for this module" \
  --context src/auth-manager.ts \
  --model gemini-2.5-flash \
  --thinking-enabled

Example 3: Using in Scripts

#!/bin/bash

# Check if authenticated
if ! gemini-mcp auth-status > /dev/null 2>&1; then
  echo "Please login first: gemini-mcp login"
  exit 1
fi

# Run analysis
gemini-mcp analyze --files "$@" --instruction "Find security vulnerabilities"

Troubleshooting

Authentication Issues

1. Browser doesn't open: Use --headless flag and manually visit the URL
2. Session expired: Run gemini-mcp login again
3. Wrong account: Use --account email@gmail.com to specify account

Connection Issues

1. Ensure Gemini CLI is installed and in PATH
2. Check internet connectivity
3. Verify Google account has access to Gemini

MCP Server Issues

1. Restart Claude Desktop/Code after configuration changes
2. Check logs for error messages
3. Verify the MCP server is running: npx @jacob/gemini-cli-mcp

Security

• Authentication tokens are stored locally in ~/.gemini-cli-mcp/auth/
• Tokens are only accessible by your user account
• Use gemini-mcp logout to clear stored credentials
• Never share your authentication cache directory

Development

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

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

# Development mode
npm run dev

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support

For issues and feature requests, please use the GitHub issue tracker.