io.github.RLabs-Inc/gemini-mcp

Official

by RLabs-Inc · TypeScript

Gemini 3 MCP server with 30+ tools: images, video, research, TTS, code exec & CLI

Gemini 3 MCP server with 30+ tools: images, video, research, TTS, code exec & CLI.

Topics: claude-code, gemini, mcp, mcp-server
Description: Gemini 3 MCP server for integrating Google's Gemini 3 models with Claude Code, enabling collaboration between AI systems. Includes a CLI.

🛠️ Key Features

Integrates Gemini 3 models with Claude Code via MCP
30+ tools including images, video, research, TTS, code execution, and CLI
MCP Registry Support for official discovery
CLI for streamlined development and testing
Markdown and web-readme excerpts for quick documentation

🚀 Use Cases

Cross-model collaboration between Gemini 3 and Claude Code
Rapid access to multimedia tooling (images, video, TTS)
Research workflows requiring code execution and CLI automation
Registry-based discovery within the MCP ecosystem

⚡ Developer Benefits

Clear MCP server architecture for Gemini-Claude integration
Ready-to-use tooling suite with extensive capabilities
Simple deployment via npm package and registry visibility
Documentation-ready readme excerpt for onboarding

⚠️ Limitations

Based on provided readme excerpt; specific tool list and API details may require runtime validation
Feature set described may evolve with MCP registry updates
External dependencies (Gemini 3, Claude Code) require compatible environments

Topics

claude-codegeminimcpmcp-server

README.md16 KBView on GitHub

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!

npm version

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

bash

# 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)

bash

# 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

bash

# 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:

code

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!):

code

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:

code

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:

code

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

gemini-end-image-edit

Close an editing session:

code

sessionId: "edit-123456789"

gemini-list-image-sessions

List all active editing sessions.

gemini-generate-video

Generate videos using Veo:

code

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:

code

operationId: "operations/xxx-xxx-xxx"

gemini-analyze-code

Analyze code for issues:

code

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

gemini-analyze-text

Analyze text content:

code

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

gemini-brainstorm

Collaborative brainstorming:

code

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

gemini-summarize

Summarize content:

code

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

gemini-run-code

Let Gemini write and execute Python code:

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:

code

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:

code

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:

code

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:

code

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:

code

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

gemini-analyze-document

Analyze PDFs and documents:

code

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

gemini-summarize-pdf

Quick PDF summarization:

code

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

gemini-extract-tables

Extract tables from documents:

code

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:

Ask Claude to design the backend API
Use gemini-generate-image for UI mockups
Ask Gemini to generate React components via gemini-query
Use multi-turn editing to refine visuals
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

bash

# 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

bash

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

Combining Preset + Explicit

bash

# 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

bash

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

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

Claude Code Configuration

json

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

If you must use a proxy to establish a connection to gemini, replace xxxx with your actual proxy port:

json

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

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

Verify your API key at Google AI Studio
Check server status: claude mcp list
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:

bash

# 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

bash

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

Install

Configuration

Environment variables

GEMINI_API_KEYrequiredsecret

Your Google Gemini API key (get one at https://aistudio.google.com/apikey)

GEMINI_OUTPUT_DIR

Directory for generated files (images, videos, audio)

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "gemini-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@rlabs-inc/gemini-mcp@0.7.1"
      ],
      "env": {
        "GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
        "GEMINI_OUTPUT_DIR": "<YOUR_GEMINI_OUTPUT_DIR>"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

MCP Server Gemini

Features

Quick Installation

MCP Server for Claude Code

CLI (Global Install)

Installation Options

Available Tools

gemini-query

gemini-generate-image

gemini-start-image-edit

gemini-continue-image-edit

gemini-end-image-edit

gemini-list-image-sessions

gemini-generate-video

gemini-check-video

gemini-analyze-code

gemini-analyze-text

gemini-brainstorm

gemini-summarize

gemini-run-code

gemini-search

gemini-structured

gemini-extract

gemini-youtube

gemini-youtube-summary

gemini-analyze-document

gemini-summarize-pdf

gemini-extract-tables

Workflow: Claude + Gemini

Environment Variables

Tool Configuration

Available Presets

Using Presets

Using Explicit Tool Lists

Combining Preset + Explicit

Available Tool Groups

Manual Installation

Global Install

Claude Code Configuration

Troubleshooting

Rate Limits (429 Errors)

Connection Issues

Image/Video Issues

Previous Versions

Development

Scripts

License

Install

Configuration

Related servers