Gemini CLI Integration Guide

February 14, 2026 · View on GitHub

Overview

This document outlines the integration with Google Gemini CLI, including version requirements, authentication, and feature implementation.

Version Compatibility

Recommended Version: v0.22.2+

This MCP server is optimized for Gemini CLI v0.22.2 or later.

Check your version:

gemini --version

Upgrade if needed:

npm update -g @google/gemini-cli

Authentication

Method 1: Google Account (Recommended)

gemini
# Follow prompts to login with Google account

Free tier limits:

60 requests/minute
1000 requests/day

Method 2: API Key

export GEMINI_API_KEY="your-api-key"

Get an API key from Google AI Studio.

Model Configuration

Setting Default Model

1. Environment Variable (Recommended):

export GEMINI_MODEL="gemini-3-pro-preview"

2. Settings File:

mkdir -p ~/.gemini
echo '{"model": {"name": "gemini-3-pro-preview"}}' > ~/.gemini/settings.json

3. Project Settings:

echo '{"model": {"name": "gemini-3-pro-preview"}}' > .gemini/settings.json

Configuration Precedence

Settings applied in order (highest priority last):

Default values
User settings (~/.gemini/settings.json)
Project settings (.gemini/settings.json)
Environment variables (GEMINI_MODEL)
Command-line arguments (-m)
MCP tool model parameter

Available Models

Model	ID	Best For
Gemini 3 Pro	`gemini-3-pro-preview`	Most capable, complex reasoning
Gemini 3 Flash	`gemini-3-flash-preview`	Fast responses, good quality
Gemini 2.5 Flash-Lite	`gemini-2.5-flash-lite`	Fastest, lightweight

Features Implementation

File Analysis with @ Syntax

The MCP server passes file references directly to Gemini CLI:

# MCP tool call
{ "prompt": "Analyze @src/main.js" }

# Translates to
gemini "Analyze @src/main.js"

Supported patterns:

@file.js - Single file
@src/*.ts - Glob pattern
@. - Current directory

Sandbox Mode

When sandbox: true is passed to ask-gemini:

gemini -s "your prompt"

Enables safe code execution in isolated environment.

YOLO Mode

When yolo: true is passed:

gemini --yolo "your prompt"

Auto-approves ALL tool executions without confirmation prompts. Required for any Gemini CLI extension that needs tool approval.

Gemini CLI Extensions

Gemini CLI supports extensions that add new capabilities. Extensions may require yolo: true to auto-approve their tool calls.

Installing Extensions:

# Install from GitHub URL
gemini extensions install https://github.com/gemini-cli-extensions/workspace

# Or from local path
gemini extensions install /path/to/extension

Popular Extensions:

Extension	Description	URL
Google Workspace	Gmail, Drive, Sheets, Docs, Calendar, Chat	`https://github.com/gemini-cli-extensions/workspace`

Usage with MCP:

{
  "prompt": "Search my Google Drive for 'budget' files and summarize them",
  "yolo": true
}

{
  "prompt": "Read the latest emails from my inbox",
  "yolo": true
}

⚠️ Security Note: Without yolo: true, extension tools will hang waiting for user approval. The YOLO flag bypasses all confirmations, so use with trusted inputs only. Never use with untrusted emails or documents (indirect prompt injection risk).

Change Mode

When changeMode: true is passed:

gemini --change-mode "your prompt"

Returns structured edits in **FILE: path:line** format with OLD/NEW blocks.

Web Search Grounding

The search tool uses Gemini's built-in Google Search grounding:

gemini --search "your query"

Returns real-time information with source attribution.

Multimodal Analysis

The analyze-media tool handles various file types:

gemini "Analyze this image" < image.png

Supports images, PDFs, and other media formats.

Error Handling

Model Fallback

When quota is exceeded on gemini-3-pro-preview:

Server detects quota error
Automatically retries with gemini-3-flash-preview
Returns result with fallback notification

Timeout Handling

For long-running operations:

Server sends progress notifications
Keeps connection alive during processing
Returns result when complete

Troubleshooting

"Command not found: gemini"

npm install -g @google/gemini-cli

"Not authenticated"

gemini  # Login with Google
# OR
export GEMINI_API_KEY="your-key"

"Quota exceeded"

Wait for quota reset (typically 1 minute)
Or use gemini-3-flash-preview model
Or upgrade to paid API tier

"File not found" with @ syntax

Use absolute paths when possible
Verify file exists: ls -la path/to/file
Check working directory

CLI Flags Reference

Flag	Description	MCP Parameter
`-m <model>`	Select model	`model`
`-s`	Enable sandbox mode	`sandbox`
`--yolo`	Auto-approve all tool calls	`yolo`
`--change-mode`	Structured edit output	`changeMode`
`--search`	Enable web search	(used by `search` tool)