MCP Server Gemini

A Model Context Protocol (MCP) server for integrating Google's Gemini 3 models with Claude Code, enabling powerful collaboration between both AI systems. Now with a beautiful CLI!

MCP Registry Support: Now discoverable in the official MCP ecosystem!

Features

Feature	Description
Deep Research Agent	Autonomous multi-step research with web search and citations
Token Counting	Count tokens and estimate costs before API calls
Text-to-Speech	30 unique voices, single speaker or two-speaker dialogues
URL Analysis	Analyze, compare, and extract data from web pages
Context Caching	Cache large documents for efficient repeated queries
YouTube Analysis	Analyze videos by URL with timestamp clipping
Document Analysis	PDFs, DOCX, spreadsheets with table extraction
4K Image Generation	Generate images up to 4K with 10 aspect ratios
Multi-Turn Image Editing	Iteratively refine images through conversation
Video Generation	Create videos with Veo 2.0 (async with polling)
Code Execution	Gemini writes and runs Python code (pandas, numpy, matplotlib)
Google Search	Real-time web information with inline citations
Structured Output	JSON responses with schema validation
Data Extraction	Extract entities, facts, sentiment from text
Thinking Levels	Control reasoning depth (minimal/low/medium/high)
Direct Query	Send prompts to Gemini 3 Pro/Flash models
Brainstorming	Claude + Gemini collaborative problem-solving
Code Analysis	Analyze code for quality, security, performance
Summarization	Summarize content at different detail levels

---

Quick Installation

MCP Server for Claude Code

# Using npm (Recommended)
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY npx -y @rlabs-inc/gemini-mcp

# Using bun
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY bunx @rlabs-inc/gemini-mcp

CLI (Global Install)

# Install globally
npm install -g @rlabs-inc/gemini-mcp

# Set your API key once (stored securely)
gcli config set api-key YOUR_KEY

# Now use any command!
gcli search "latest news"
glci image "sunset over mountains" --ratio 16:9

Get your API key: Visit Google AI Studio - it's free and takes seconds!

Installation Options

# With verbose logging
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY VERBOSE=true bunx -y @rlabs-inc/gemini-mcp

# With custom output directory for generated images/videos
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY GEMINI_OUTPUT_DIR=/path/to/output bunx -y @rlabs-inc/gemini-mcp

---

Available Tools

gemini-query

Direct queries to Gemini with thinking level control:

prompt: "Explain quantum entanglement"
model: "pro" or "flash"
thinkingLevel: "low" | "medium" | "high" (optional)

• low: Fast responses, minimal reasoning
• medium: Balanced (Flash only)
• high: Deep reasoning for complex tasks (default)

gemini-generate-image

Generate images with Nano Banana Pro (Claude can SEE them!):

prompt: "a futuristic city at sunset"
style: "cyberpunk" (optional)
aspectRatio: "16:9" (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9)
imageSize: "2K" (1K, 2K, 4K)
useGoogleSearch: false (ground in real-world info)
thinkingLevel: "high" (optional - minimal, low, medium, high)
personGeneration: "ALLOW_ALL" (optional - ALLOW_ALL, ALLOW_ADULT, ALLOW_NONE)
seed: 42 (optional - for reproducible results)

gemini-start-image-edit

Start a multi-turn image editing session:

prompt: "a cozy cabin in the mountains"
aspectRatio: "16:9"
imageSize: "2K"
useGoogleSearch: false
thinkingLevel: "high" (optional - minimal, low, medium, high)
personGeneration: "ALLOW_ALL" (optional - ALLOW_ALL, ALLOW_ADULT, ALLOW_NONE)
seed: 42 (optional - for reproducible results)

Returns a session ID for iterative editing.

gemini-continue-image-edit

Continue refining an image:

sessionId: "edit-123456789"
prompt: "add snow on the roof and make it nighttime"

gemini-end-image-edit

Close an editing session:

sessionId: "edit-123456789"

gemini-list-image-sessions

List all active editing sessions.

gemini-generate-video

Generate videos using Veo:

prompt: "a cat playing piano"
aspectRatio: "16:9" (optional)
negativePrompt: "blurry, text" (optional)

Video generation is async (takes 1-5 minutes). Use gemini-check-video to poll.

gemini-check-video

Check video generation status and download when complete:

operationId: "operations/xxx-xxx-xxx"

gemini-analyze-code

Analyze code for issues:

code: "function foo() { ... }"
language: "typescript" (optional)
focus: "quality" | "security" | "performance" | "bugs" | "general"

gemini-analyze-text

Analyze text content:

text: "Your text here..."
type: "sentiment" | "summary" | "entities" | "key-points" | "general"

gemini-brainstorm

Collaborative brainstorming:

prompt: "How could we implement real-time collaboration?"
claudeThoughts: "I think we should use WebSockets..."
maxRounds: 3 (optional)

gemini-summarize

Summarize content:

content: "Long text to summarize..."
length: "brief" | "moderate" | "detailed"
format: "paragraph" | "bullet-points" | "outline"

gemini-run-code

Let Gemini write and execute Python code:

prompt: "Calculate the first 50 prime numbers and plot them"
data: "optional CSV data to analyze" (optional)

Supports libraries: numpy, pandas, matplotlib, scipy, scikit-learn, tensorflow, and more. Generated charts are saved to the output directory and returned as images.

gemini-search

Real-time web search with citations:

query: "What happened in tech news this week?"
returnCitations: true (default)

Returns grounded responses with inline citations and source URLs.

gemini-structured

Get JSON responses matching a schema:

prompt: "Extract the meeting details from this email..."
schema: '{"type":"object","properties":{"date":{"type":"string"},"attendees":{"type":"array"}}}'
useGoogleSearch: false (optional)

gemini-extract

Convenience tool for common extraction patterns:

text: "Your text to analyze..."
extractType: "entities" | "facts" | "summary" | "keywords" | "sentiment" | "custom"
customFields: "name, date, amount" (for custom extraction)

gemini-youtube

Analyze YouTube videos directly:

url: "https://www.youtube.com/watch?v=..."
question: "What happens at 2:30?"
startTime: "1m30s" (optional, for clipping)
endTime: "5m00s" (optional, for clipping)

gemini-youtube-summary

Quick video summarization:

url: "https://www.youtube.com/watch?v=..."
style: "brief" | "detailed" | "bullet-points" | "chapters"

gemini-analyze-document

Analyze PDFs and documents:

filePath: "/path/to/document.pdf"
question: "Summarize the key findings"
mediaResolution: "low" | "medium" | "high"

gemini-summarize-pdf

Quick PDF summarization:

filePath: "/path/to/document.pdf"
style: "brief" | "detailed" | "outline" | "key-points"

gemini-extract-tables

Extract tables from documents:

filePath: "/path/to/document.pdf"
outputFormat: "markdown" | "csv" | "json"

---

Workflow: Claude + Gemini

The killer combination for development:

Claude	Gemini
Complex logic	Frontend/UI
Architecture	Visual components
Backend code	Image generation
Integration	React/CSS styling
Reasoning	Creative generation

Example workflow:

1. Ask Claude to design the backend API
2. Use gemini-generate-image for UI mockups
3. Ask Gemini to generate React components via gemini-query
4. Use multi-turn editing to refine visuals
5. Let Claude wire everything together

---

Environment Variables

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	-	Your Google Gemini API key
GEMINI_OUTPUT_DIR	No	./gemini-output	Where to save generated files
GEMINI_MODEL	No	-	Override model for init test
GEMINI_PRO_MODEL	No	gemini-3-pro-preview	Pro model (Gemini 3)
GEMINI_FLASH_MODEL	No	gemini-3-flash-preview	Flash model (Gemini 3)
GEMINI_IMAGE_MODEL	No	gemini-3-pro-image-preview	Image model (Nano Banana Pro)
GEMINI_IMAGE_THINKING_LEVEL	No	high	Default thinking level for image generation (minimal, low, medium, high)
GEMINI_VIDEO_MODEL	No	veo-2.0-generate-001	Video model
VERBOSE	No	false	Enable verbose logging
QUIET	No	false	Minimize logging
GEMINI_ENABLED_TOOLS	No	-	Comma-separated list of tool groups to load (e.g., query,search,image-gen)
GEMINI_TOOL_PRESET	No	-	Preset profile: minimal, text, image, research, media, full

---

Tool Configuration

By default, all 37 tools are loaded. To reduce context usage, configure which tools to load:

Available Presets

Preset	Tool Groups
minimal	query, brainstorm
text	query, brainstorm, analyze, summarize, structured
image	query, image-gen, image-edit, image-analyze
research	query, search, deep-research, url-context, document
media	query, image-gen, image-edit, image-analyze, video-gen, youtube, speech
full	All 18 tool groups (default)

Using Presets

# Minimal - query and brainstorm
GEMINI_TOOL_PRESET=minimal

# Text processing
GEMINI_TOOL_PRESET=text  # query, brainstorm, analyze, summarize, structured

# Image workflows
GEMINI_TOOL_PRESET=image  # query, image-gen, image-edit, image-analyze

# Research workflows
GEMINI_TOOL_PRESET=research  # query, search, deep-research, url-context, document

Using Explicit Tool Lists

# Only specific tools
GEMINI_ENABLED_TOOLS=query,search,image-gen

Combining Preset + Explicit

# Start with preset, add extras
GEMINI_TOOL_PRESET=minimal
GEMINI_ENABLED_TOOLS=search,image-gen  # Adds to minimal preset

Available Tool Groups

Group	Tools
query	gemini-query
brainstorm	gemini-brainstorm
analyze	gemini-analyze-code, gemini-analyze-text
summarize	gemini-summarize
image-gen	gemini-generate-image, gemini-image-prompt
image-edit	gemini-start-image-edit, gemini-continue-image-edit, gemini-end-image-edit, gemini-list-image-sessions
video-gen	gemini-generate-video, gemini-check-video
code-exec	gemini-run-code
search	gemini-search
structured	gemini-structured, gemini-extract
youtube	gemini-youtube, gemini-youtube-summary
document	gemini-analyze-document, gemini-summarize-pdf, gemini-extract-tables
url-context	gemini-analyze-url, gemini-compare-urls, gemini-extract-from-url
cache	gemini-create-cache, gemini-query-cache, gemini-list-caches, gemini-delete-cache
speech	gemini-speak, gemini-dialogue, gemini-list-voices
token-count	gemini-count-tokens
deep-research	gemini-deep-research, gemini-check-research, gemini-research-followup
image-analyze	gemini-analyze-image

---

Manual Installation

Global Install

# Using npm
npm install -g @rlabs-inc/gemini-mcp

# Using bun
bun install -g @rlabs-inc/gemini-mcp

Claude Code Configuration

{
  "gemini": {
    "command": "npx",
    "args": ["-y", "@rlabs-inc/gemini-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-api-key",
      "GEMINI_OUTPUT_DIR": "/path/to/save/files"
    }
  }
}

---

Troubleshooting

Rate Limits (429 Errors)

If you're hitting rate limits on the free tier:

• Set GEMINI_MODEL=gemini-3-flash-preview to use Flash for init (higher limits)
• Or upgrade to a paid plan

Connection Issues

1. Verify your API key at Google AI Studio
2. Check server status: claude mcp list
3. Try with verbose logging: VERBOSE=true

Image/Video Issues

• Ensure your API key has access to image/video generation
• Check output directory permissions
• Files save to GEMINI_OUTPUT_DIR (default: ./gemini-output)
• For 4K images, generation takes longer

---

Previous Versions

0.7.2

Beautiful CLI with Themes! Use Gemini directly from your terminal:

# Install globally
npm install -g @rlabs-inc/gemini-mcp

# Set your API key once
gcli config set api-key YOUR_KEY

# Generate images, videos, search, research, and more!
gcli image "a cat astronaut" --size 4K
gcli search "latest AI news"
gcli research "quantum computing applications" --wait
gcli speak "Hello world" --voice Puck

5 Beautiful Themes: terminal, neon, ocean, forest, minimal

CLI Commands:

• gcli query - Direct Gemini queries with thinking levels
• gcli search - Real-time web search with citations
• gcli research - Deep research agent
• gcli image - Generate images (up to 4K)
• gcli video - Generate videos with Veo
• gcli speak - Text-to-speech with 30 voices
• gcli tokens - Count tokens and estimate costs
• gcli config - Manage settings

v0.6.x: Deep Research, Token Counting, TTS, URL analysis, Context Caching v0.5.x: 30+ tools, YouTube analysis, Document analysis v0.4.x: Code execution, Google Search v0.3.x: Thinking levels, Structured output, 4K images v0.2.x: Image/Video generation with Veo

---

Development

git clone https://github.com/rlabs-inc/gemini-mcp.git
cd gemini-mcp
bun install
bun run build
bun run dev -- --verbose

Scripts

Command	Description
bun run build	Build for production
bun run dev	Development mode with watch
bun run typecheck	Type check without emitting
bun run format	Format with Prettier
bun run lint	Lint with ESLint

---

License

MIT License

---

Made with Claude + Gemini working together