Model Context Protocol server for Google Gemini AI with chat, research, and grounding
io.github.houtini-ai/gemini — Model Context Protocol server for Google Gemini
Model Context Protocol (MCP) server for Google Gemini AI. It provides chat, research, and grounding, and includes capabilities for image generation and video generation, with search grounding integrated into Claude. The repository is associated with the @houtini/gemini-mcp package and is listed on the MCP Registry.
🛠️ Key Features
Chat
Research
Grounding
Image generation
Video generation
Search grounding inside Claude
🚀 Use Cases
Gemini-based chat workflows
Research and grounded responses using search grounding
Generating images and videos from within Claude-integrated flows
⚡ Developer Benefits
Exposes Gemini functionality via MCP
Tagged for MCP apps and model-context-protocol compatibility
Gemini MCP - Google Gemini image generation, video and search grounding inside Claude
I've had this Gemini MCP server running in my Claude Desktop setup for the best part of a year now. It's one of the few I leave switched on permanently. Not because Gemini replaces Claude (it doesn't), but because grounded search, image generation, SVG diagrams and video are things Gemini happens to do well, and having them as tools inside Claude beats flipping between browser tabs.
Fourteen tools, built around the models people actually come looking for: Nano Banana Pro (gemini-3-pro-image) and Nano Banana 2 for images, Veo 3.1 for video with synchronised audio, Gemini 4 Argon for chat and Gemini 3.1 Pro for deep research, both with Google Search grounding. Everything previews inline in Claude Desktop through MCP Apps rather than landing as a file path you have to go and open.
One npx command. That's it.
New here? The full user guide walks through every tool, the free-tier gotcha, and what to do when something breaks.
Everything below came out of the tools in this repo, unretouched, on the afternoon I wrote this. Prompts are in the captions so you can judge for yourself.
Image generation with search grounding. One generate_image call with use_search=true. Gemini looked up the actual Met Office forecast for the week, then drew it. The dates and temperatures are real (well, as real as a forecast gets).
Prompt: "A polished editorial infographic poster: London weather, this week. Use real forecast data from search for the next 5 days..." - gemini-3-pro-image, 16:9, 2K.
Text that's actually spelled correctly. This is the thing Nano Banana Pro does that the previous generation of image models couldn't. Every label here is straight out of the model.
Prompt: "A clean, magazine-quality infographic titled How an MCP tool call works, with four numbered steps..." - gemini-3-pro-image.
Generate, then edit. Left is generate_image. Right is edit_image on that file with one sentence of instructions: change the track to Monza in daylight, swap the rim lighting for window light, make the pedals red. Same cockpit, same camera angle.
generate_image
edit_image
Image to video with Veo 3.1. The night-time cockpit above, passed to generate_video as firstFrameImage. Eight seconds at 1080p with generated audio (engine note, tyre hiss) - the GIF below is silent and squashed for GitHub, the real file is a proper MP4.
Veo 3.1 video: the cockpit comes to life, hands turning the wheel through Eau Rouge
SVG that you can actually use. Not a picture of a diagram - real vector markup you can drop into a page, edit by hand or commit to a repo. Both of these are the raw .svg files the tool wrote to disk.
generate_svg style=technical
generate_svg style=data-viz
A landing page from a paragraph.generate_landing_page with a brief, a company name and a brand colour. Self-contained HTML, inline CSS, the little chart in the hero is animated SVG. Screenshot of the file opened in Chrome, nothing else touched.
And the fast one. Nano Banana 2 (gemini-3.1-flash-image) for when you want volume rather than 4K. This took about ten seconds.
A word on the free tier, because the defaults lean on a paid model. Google's pricing page gives Gemini 3 Flash Preview a free tier, but the flagship models are paid-only - and gemini-4-argon is the default for gemini_chat and generate_landing_page, with gemini-3.1-pro-preview the default for gemini_deep_research (synthesis) and analyze_image. On a free key those calls will fail unless you point them at a free model: set GEMINI_DEFAULT_MODEL=gemini-3-flash-preview (covers chat and landing pages), GEMINI_DEEP_RESEARCH_MODEL and GEMINI_IMAGE_ANALYSIS_MODEL likewise, or pass model per call. generate_svg already defaults to gemini-3-flash-preview. Check the pricing page for the other models before relying on them - Google changes these tiers.
Claude Code doesn't read claude_desktop_config.json. Use claude mcp add instead:
bash
claude mcp add -e GEMINI_API_KEY=your-api-key-here -s user gemini -- npx -y @houtini/gemini-mcp
With an output directory for images and video:
bash
claude mcp add \
-e GEMINI_API_KEY=your-api-key-here \
-e GEMINI_IMAGE_OUTPUT_DIR=/path/to/output \
-s user \
gemini -- npx -y @houtini/gemini-mcp
Check with claude mcp get gemini - you want to see Status: Connected.
What it does
Chat with Google Search grounding
code
Use gemini:gemini_chat to ask: "What changed in the MCP spec in the last month?"
Grounding is on by default. Gemini searches Google before it answers, so you get this month's information rather than a training-cutoff guess, and the sources come back as markdown links. For questions where you want pure reasoning ("explain this code", that sort of thing) set grounding: false.
Runs on gemini-4-argon (Gemini 4 Argon) unless you say otherwise. Pass model: "gemini-3.8-flash" if you'd rather have speed than depth, or model: "gemini-3.1-pro-preview" for the previous flagship. thinking_level works on Gemini 3.x and 4 models: high for the hard stuff, low to keep it snappy.
Deep research
code
Use gemini:gemini_deep_research with:
research_question="What are the current approaches to AI agent memory management?"
max_iterations=5
Runs grounded search passes and then writes them up as one report. The passes run on gemini-3.8-flash with low thinking (they're gathering facts, not reasoning about them), and the synthesis at the end runs on gemini-3.1-pro-preview with high thinking. Two passes plus a synthesis is the default and lands in two to three minutes.
That split matters more than it sounds. Earlier versions ran everything on Pro with full thinking, and one pass on a broad question could run past Claude Desktop's four-minute timeout on its own. Keep max_iterations at 2 or 3 in Claude Desktop; in an IDE or an agent framework, 5 to 7 produces noticeably better synthesis. focus_areas takes an array if you want to steer each pass.
Image generation with search grounding
code
Use gemini:generate_image with:
prompt="Stock price chart showing Apple (AAPL) closing prices for the last 5 trading days"
use_search=true
aspectRatio="16:9"
Default model is gemini-3-pro-image, which is Nano Banana Pro now that it's out of preview. It renders legible text, does 4K, and it's the only one that supports conversational editing. gemini-3.1-flash-image (Nano Banana 2) is the fast option - not far off in quality, a fraction of the time and the cost. There's a Lite variant too if you're doing hundreds.
With use_search=true, Gemini looks things up before it draws. Weather, prices, sports results, that kind of data-driven image works reliably. The full-resolution file always goes to disk; the inline preview is resized to fit the MCP transport cap but the original is untouched.
Video generation with Veo 3.1
code
Use gemini:generate_video with:
prompt="A close-up shot of a futuristic coffee machine brewing a glowing blue espresso, steam rising dramatically. Cinematic lighting."
resolution="1080p"
durationSeconds=8
Google's Veo 3.1. Four to eight second clips at up to 4K with native, synchronised audio. It's asynchronous on Google's side and takes two to five minutes; the tool polls until it's ready so you don't have to.
Options worth knowing about:
aspectRatio - 16:9 landscape or 9:16 for vertical
generateAudio - on by default; dialogue and effects that match the prompt
firstFrameImage - animate from a still (that's how the cockpit clip above was made)
referenceImages - up to three, for character or style consistency
sampleCount - up to four variations in one call
seed - deterministic output across runs
generateThumbnail - pulls a frame out with ffmpeg, if you've got it in PATH
model - veo-3.1-lite-generate-preview if you want cheaper and faster
SVG generation
This is the one people underestimate. The output isn't a picture of a diagram, it's the SVG markup itself - drop it into a codebase, a slide, a web page, and it scales without a single raster artefact.
code
Use gemini:generate_svg with:
prompt="Architecture diagram showing a microservices system with API gateway, three services, and a shared database"
style="technical"
width=1000
height=600
Four styles:
Style
Best for
technical
Architecture diagrams, flowcharts, system maps
artistic
Illustrations, decorative graphics, icons
minimal
Clean data visualisations, simple charts
data-viz
Charts, dashboards, infographics
You get real SVG code back. Edit it, animate it, embed it, commit it. No export step, no Figma.
Runs on gemini-3-flash-preview unless you pass model - it's quick, it handles SVG markup comfortably, and it has a free tier. Pass model: "gemini-3.1-pro-preview" for denser diagrams if you're on a paid key.
Image editing and analysis
Conversational editing. Nano Banana Pro keeps context between turns. Pass the thought signature from the previous call back in and it remembers what it was working on:
code
Use gemini:edit_image with:
prompt="Change the colour scheme to blue and green"
images=[{filePath: "C:/output/gemini-123.png", thoughtSignature: "fromPreviousCall"}]
Analysis, two tools for two jobs:
describe_image - quick general descriptions on gemini-3.8-flash
analyze_image - structured extraction and proper reasoning on gemini-3.1-pro-preview
Local files:
code
Use gemini:load_image_from_path with filePath="C:/screenshots/error.png"
Or just pass filePath straight into any image tool's images array and the server reads it itself - that skips the MCP transport limit entirely.
Media resolution control
Cut token usage by up to 75% where the task doesn't need the detail:
Level
Tokens
Savings
Best for
MEDIA_RESOLUTION_LOW
280
75%
Simple tasks, bulk operations
MEDIA_RESOLUTION_MEDIUM
560
50%
PDFs and documents (OCR saturates here)
MEDIA_RESOLUTION_HIGH
1120
default
Detailed analysis
MEDIA_RESOLUTION_ULTRA_HIGH
2000+
per-image only
Maximum detail
For PDF OCR, MEDIUM gives me identical text extraction to HIGH at half the tokens. I've not found a case where it didn't.
Landing page generation
code
Use gemini:generate_landing_page with:
brief="A SaaS tool that helps developers monitor API latency"
companyName="PingWatch"
primaryColour="#6366F1"
style="startup"
sections=["hero", "features", "pricing", "cta"]
One self-contained HTML file: inline CSS, vanilla JS, no external dependencies. Styles are minimal, bold, corporate and startup. The PingWatch page in the gallery above is exactly this call.
Professional chart design systems
gemini_prompt_assistant carries nine chart design systems you can ask for by name:
System
Inspiration
Best for
storytelling
Cole Nussbaumer Knaflic
Executive presentations
financial
Financial Times
Editorial journalism - FT pink, serif titles
terminal
Bloomberg / fintech
High-density dark mode with neon
modernist
W.E.B. Du Bois
Bold geometric blocks, stark contrasts
professional
IBM Carbon / Tailwind
Enterprise dashboards
editorial
FiveThirtyEight / Economist
Data journalism
scientific
Nature / Science
Academic rigour
minimal
Edward Tufte
Maximum data-ink ratio
dark
Observable
Modern dark mode
Help system
code
Use gemini:gemini_help with topic="overview"
The full documentation without leaving Claude. Topics: overview, image_generation, image_editing, image_analysis, chat, deep_research, grounding, media_resolution, models, all.
Image output and storage
By default, images come back as inline previews rendered directly in Claude, and the full-size file is written next to the package. Set GEMINI_IMAGE_OUTPUT_DIR if you'd rather they all landed somewhere sensible:
Resized JPEG for inline transport, sized to fit under the cap
Gemini returns 2 to 5 MB images. The resize measures the non-image overhead in each response, works out the binary budget left, and steps the preview down (800, 600, 400, 300, 200px) until it fits under the 1 MB MCP transport limit. The full image is always there on disk.
Inline viewers in Claude Desktop
Image, SVG, video and landing-page results each open in an MCP App viewer with zoom, the saved path and a copy button. If you're on Claude Desktop and the viewer sat on "Waiting for image..." forever in an older version, that was Claude Desktop stripping the structured data the viewer reads (ext-apps#696). Since 2.7.0 the viewer fetches it back from the server itself, so it renders either way.
Model for the grounded search passes in gemini_deep_research
GEMINI_IMAGE_ANALYSIS_MODEL
No
gemini-3.1-pro-preview
Model for analyze_image
GEMINI_IMAGE_DESCRIBE_MODEL
No
gemini-3.8-flash
Model for describe_image
GEMINI_IMAGE_GENERATION_MODEL
No
gemini-3-pro-image
Model for generate_image and edit_image
GEMINI_DEFAULT_GROUNDING
No
true
Set to false to turn Google Search grounding off by default
GEMINI_IMAGE_OUTPUT_DIR
No
-
Where generated images and videos are saved
GEMINI_ALLOW_EXPERIMENTAL
No
false
Include experimental and preview models in auto-discovery
GEMINI_REQUEST_TIMEOUT_MS
No
240000
Per-request timeout for chat and analysis calls, in milliseconds
GEMINI_MCP_RETRY_ATTEMPTS
No
3
Total attempts per Gemini API request. Transient network failures (fetch failed, ECONNRESET, proxy or VPN drops) are retried with backoff. 1 disables it
GEMINI_MCP_LOG_FILE
No
false
Write logs to ~/.gemini-mcp/logs/
DEBUG_MCP
No
false
Log to stderr for debugging tool calls
Tools reference
Tool
Description
gemini_chat
Chat with Gemini 4 Argon. Google Search grounding on by default. Supports thinking_level
gemini_deep_research
Grounded search passes on Flash, synthesised into a report by 3.1 Pro. Default 2 passes
gemini_list_models
Lists the models your API key can see, live
gemini_help
Documentation for every tool without leaving Claude
gemini_prompt_assistant
Expert guidance for image generation with nine chart design systems
generate_image
Image generation with optional search grounding. Full-res saved to disk
edit_image
Edit images with natural-language instructions. Multi-turn continuity via thought signatures
describe_image
Fast image descriptions on Gemini 3.8 Flash
analyze_image
Structured extraction and analysis on Gemini 3.1 Pro
load_image_from_path
Read a local image file and return base64 for any image tool
generate_video
Video generation with Veo 3.1: 4 to 8 seconds at up to 4K with native audio
generate_svg
Production-ready SVG: diagrams, illustrations, icons, data visualisations
generate_landing_page
Self-contained HTML landing pages with inline CSS and JS
gemini_viewer_payload
Internal. The inline viewers use it to fetch their display data; you'll never call it
Model reference
Checked against the live models API on 22 September 2026. gemini_list_models will tell you what your key can see today.
Model
Used by
Notes
gemini-4-argon
gemini_chat, generate_landing_page
Default. Gemini 4 Argon - the current flagship. Paid-only - no free tier
gemini-3.1-pro-preview
gemini_deep_research (synthesis), analyze_image
Default for those two. Strong reasoning, paid-only - no free tier
Older IDs, still accepted so existing configs keep working
veo-3.1-generate-preview
generate_video
Default. Cinematic, native audio, up to 4K
veo-3.1-lite-generate-preview
generate_video
Cheaper and faster on the same API
Why the defaults are what they are. I went back and forth on this. Gemini 3.8 Flash is GA and newer, but 3.1 Pro is still what Google calls its strongest reasoning model, and reasoning is the point of gemini_chat and deep research - so Pro stays the default there, and Flash takes the lighter describe_image job. For images, Nano Banana Pro left preview and kept its quality lead, so it's the default; Nano Banana 2 is there when you'd rather trade a little quality for a lot of speed. Gemini's newer Omni video model uses a different API, so it's not wired in yet.
Gemini 3 notes: temperature is forced to 1.0 on every 3.x model (Google's requirement, lower values cause looping). thinking_level applies to gemini_chat.
Token budgets:max_tokens defaults to each model's full output ceiling as reported live by the models API (65,536 on current Gemini 3 text models; the 1M figure is input context). It's a cap, not consumption, so unused headroom costs nothing. Values below 4,096 are ignored because Gemini 3 thinking burns tiny budgets before you see any output, which looks exactly like a timeout, and values above the model's real limit are clamped.