API Reference

Overview

Complete reference for the Gemini MCP Server tools and interfaces.

This server implements the MCP 2025-11-25 specification, including tool annotations and progress notifications.

MCP Protocol Features

Tool Annotations

All tools include annotations that provide hints to MCP clients about tool behavior:

Annotation	Type	Description
title	string	Human-readable tool name
readOnlyHint	boolean	Tool doesn't modify state
destructiveHint	boolean	Tool may modify files or external state
idempotentHint	boolean	Multiple calls produce same result
openWorldHint	boolean	Tool interacts with external services

Tool Annotation Matrix

Tool	Title	readOnlyHint	destructiveHint	idempotentHint	openWorldHint
gemini	Query Gemini AI	false	true	false	true
web-search	Web Search	true	false	false	true
analyze-media	Analyze Media	true	false	false	true
shell	Shell Commands	false	true	false	true
brainstorm	Brainstorm Ideas	true	false	false	true
fetch-chunk	Fetch Response Chunk	true	false	true	false
ping	Ping Server	true	false	true	false
help	Get Help	true	false	true	false
timeout-test	Test Timeout	true	false	true	false

Progress Notifications

For long-running operations, the server sends notifications/progress messages when the client includes a progressToken in the request _meta.

Supported Tools: gemini, web-search, analyze-media, shell, brainstorm

---

Tools

gemini - File Analysis & Questions

Analyze files and codebases using Gemini's large context window with the @ syntax.

Parameters

Parameter	Type	Required	Default	Description
prompt	string	Yes	-	Your question or analysis request. Use @ syntax for file references
model	string	No	gemini-3-pro-preview	Model to use
sandbox	boolean	No	false	Enable sandbox mode for safe execution
yolo	boolean	No	false	Auto-approve all tool executions (required for Google Workspace)
changeMode	boolean	No	false	Enable structured edit mode
chunkIndex	number	No	-	Chunk to retrieve (1-based) for large responses
chunkCacheKey	string	No	-	Cache key from previous chunked response

Model Options

• gemini-3-pro-preview (default) - Most capable, complex reasoning
• gemini-3-flash-preview - Fast responses, good quality
• gemini-2.5-flash-lite - Fastest, lightweight

YOLO Mode

When yolo: true is set, Gemini auto-approves all tool executions without confirmation prompts. Required for Gemini CLI extensions that need tool approval (e.g., Google Workspace, custom extensions).

{
  "prompt": "Search my Google Drive for budget spreadsheets",
  "yolo": true
}

Installing Extensions:

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

# Install from local path
gemini extensions install /path/to/your-extension

⚠️ Security: Without yolo: true, extension tools will hang waiting for approval. YOLO bypasses all confirmations—use with trusted inputs only.

Examples

Basic Usage:

{
  "prompt": "Analyze @src/main.js and explain what it does"
}

With Model Selection:

{
  "prompt": "Quickly summarize @package.json",
  "model": "gemini-3-flash-preview"
}

Change Mode:

{
  "prompt": "Refactor @src/utils.ts for better error handling",
  "changeMode": true
}

Google Workspace:

{
  "prompt": "Read the 'Sales Q4' spreadsheet and summarize the data",
  "yolo": true
}

---

web-search - Web Search

Search the web using Gemini with Google Search grounding for real-time information.

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	-	Search query
summarize	boolean	No	true	Summarize results
model	string	No	gemini-3-flash-preview	Model to use

Examples

Basic Usage:

{
  "query": "latest React 19 features"
}

Raw Results:

{
  "query": "kubernetes security best practices 2025",
  "summarize": false
}

---

analyze-media - Multimodal Analysis

Analyze images, PDFs, screenshots, and diagrams using Gemini's multimodal capabilities.

Parameters

Parameter	Type	Required	Default	Description
filePath	string	Yes	-	Path to media file (use @ syntax)
prompt	string	Yes	-	What to analyze or extract
model	string	No	gemini-3-pro-preview	Model to use
detailed	boolean	No	false	Provide detailed analysis

Supported Formats

• Images: PNG, JPG, GIF, WebP
• Documents: PDF
• Screenshots: Any image format

Examples

Basic Usage:

{
  "filePath": "@screenshot.png",
  "prompt": "describe this UI"
}

Detailed Analysis:

{
  "filePath": "@architecture.pdf",
  "prompt": "explain the system design",
  "detailed": true
}

---

shell - Shell Command Generation

Generate and optionally execute shell commands using Gemini.

Parameters

Parameter	Type	Required	Default	Description
task	string	Yes	-	Description of the shell task
dryRun	boolean	No	true	Explain commands without executing
workingDirectory	string	No	-	Working directory for execution
model	string	No	gemini-3-flash-preview	Model to use

Examples

Dry Run (default):

{
  "task": "find all TypeScript files larger than 100KB"
}

Execute:

{
  "task": "run the test suite",
  "dryRun": false
}

---

brainstorm - Creative Ideation

Generate ideas using various brainstorming methodologies.

Parameters

Parameter	Type	Required	Default	Description
prompt	string	Yes	-	The brainstorming topic
methodology	string	No	auto	Framework to use
domain	string	No	-	Domain context for specialized ideas
constraints	string	No	-	Known limitations or requirements
ideaCount	number	No	-	Target number of ideas
includeAnalysis	boolean	No	false	Include feasibility analysis

Methodology Options

• auto - Automatically select best methodology
• divergent - Generate many diverse ideas
• convergent - Focus and refine ideas
• SCAMPER - Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, Reverse
• design-thinking - Empathize, Define, Ideate, Prototype, Test
• lateral - Lateral thinking techniques

Examples

Basic Usage:

{
  "prompt": "ideas for improving user onboarding"
}

With Methodology:

{
  "prompt": "improve the checkout flow",
  "methodology": "SCAMPER",
  "includeAnalysis": true
}

---

fetch-chunk - Retrieve Cached Chunks

Retrieve cached chunks from large changeMode responses.

Parameters

Parameter	Type	Required	Default	Description
cacheKey	string	Yes	-	Cache key from previous response
chunkIndex	number	Yes	-	Chunk index to retrieve (1-based)

Notes

• Cache TTL: 10 minutes
• Used for retrieving large structured edit responses

---

ping - Connection Test

Test if the MCP server is working properly.

Parameters

None.

Response

Returns server status and version information.

---

help - Gemini CLI Help

Get information about Gemini CLI capabilities and commands.

Parameters

None.

Response

Returns Gemini CLI help output.

---

Advanced Features

Large File Handling

• Gemini's massive context window handles large files exceeding other models' limits
• Use @ syntax: @src/main.js, @. (current directory)
• Automatic chunking for very large responses

Change Mode (Structured Edits)

When changeMode is enabled:

• Responses formatted as structured edits
• Parses **FILE: path:line** format with OLD/NEW blocks
• Chunks large responses for manageable processing
• 10-minute cache TTL for chunk retrieval

Model Fallback

• Automatic fallback from gemini-3-pro-preview to gemini-3-flash-preview on quota exceeded
• Transparent retry with status notification