@voidog/gemini-mcp

An MCP (Model Context Protocol) server that integrates Gemini CLI with Claude Code. This server enables Claude Code to leverage Gemini's capabilities including chat, session management, and image generation.

Prerequisites

• Node.js >= 20
• Gemini CLI installed and authenticated (npm install -g @google/gemini-cli && gemini)

Installation

Using npx (recommended)

No installation required — use npx directly when registering the MCP server:

claude mcp add gemini-mcp -- npx -y @voidog/gemini-mcp

Global install

npm install -g @voidog/gemini-mcp
claude mcp add gemini-mcp -- gemini-mcp

Important Notes

• This server runs Gemini CLI in YOLO mode (-y flag), which auto-accepts all tool calls without user confirmation. This is by design for non-interactive MCP usage, but be aware that Gemini may execute file operations, web requests, or other actions autonomously.
• Image generation requires the nanobanana extension for Gemini CLI. Install it with: gemini extensions install nanobanana

Available Tools

Tool	Description
gemini_chat	Start a new Gemini chat session (headless + YOLO mode). Accepts model and extensions.
gemini_chat_session	Continue an existing session with a new prompt. Accepts model and extensions.
gemini_list_sessions	List available sessions
gemini_resume_session	Resume a session by ID, index, or "latest". Accepts model and extensions.
gemini_delete_session	Delete a session by index
gemini_list_extensions	List installed Gemini CLI extensions
gemini_list_models	List available Gemini models
gemini_generate_image	Generate images via the nanobanana extension

Chat Models

• gemini-3.1-pro-preview — reasoning-heavy tasks (default)
• gemini-3-flash-preview — speed-first tasks

Image Generation Models

• gemini-3.1-flash-image-preview
• gemini-3-pro-image-preview
• gemini-2.5-flash-image

File Sharing

The gemini_chat, gemini_chat_session, and gemini_resume_session tools accept a files parameter — an array of absolute file paths. File contents are piped to Gemini CLI via stdin, since the @ file reference syntax does not work in headless mode.

Limits: Each file must be under 5 MB, with a 20 MB total limit and a maximum of 20 files per request.

Example usage (from Claude Code):

Use gemini_chat with prompt "Explain this code" and files ["/home/user/project/src/main.ts"]

Troubleshooting

Truncated Responses (8K Token Limit)

By default, Gemini CLI limits output to ~8,192 tokens due to an upstream API default. This can cause long responses to be silently truncated. gemini-mcp detects truncation and appends a warning, but to fix the root cause, add the following to your Gemini CLI settings (~/.gemini/settings.json):

{
  "maxOutputTokens": 65536
}

This increases the output limit to 64K tokens. See google-gemini/gemini-cli#23081 for details.

Environment Variables

Variable	Default	Description
GEMINI_BINARY	gemini	Path to the Gemini CLI binary
GEMINI_IMAGE_OUTPUT_DIR	./gemini-mcp-output	Directory for generated images

Development

git clone https://github.com/voidog/gemini-mcp.git
cd gemini-mcp
npm install
npm run build
npm test

License

MIT