Gemini MCP

Gemini MCP - Google Gemini image generation, video and search grounding inside Claude

I've been running this Gemini MCP server in my Claude Desktop setup for months. It's one of the few I leave on permanently — not because Gemini replaces Claude, but because grounded search, image generation, SVG diagrams, and video are things Gemini does well. Having them as tools inside Claude beats switching browser tabs.

Thirteen tools, covering the models people actually come looking for:Nano Banana Pro(gemini-3-pro-image-preview) for image generation,Veo 3.1for video with synchronised audio, andGemini 3.1 Profor chat and deep research with Google Search grounding. Images, SVGs and video preview inline in Claude Desktop through MCP Apps rather than landing as a file path you have to go and open.

Get started|What it does|SVG generation|Image output|Configuration|Tools|Models|Requirements

Go toGoogle AI Studioand create one. The free tier covers most development use — you'll hit rate limits on deep research if you're hammering it, but for day-to-day work it's fine.

{ "mcpServers": { "gemini": { "command": "npx", "args": ["@houtini/gemini-mcp"], "env": { "GEMINI_API_KEY": "your-api-key-here" } } } }

That's it. Tools show up automatically.npxpulls the package on first run — no separate install needed.

For development, or if you'd rather not rely on npx:

git clone https://github.com/houtini-ai/gemini-mcp cd gemini-mcp npm install --include=dev npm run build

Then point your config at the local build:

{ "mcpServers": { "gemini": { "command": "node", "args": ["C:/path/to/gemini-mcp/dist/index.js"], "env": { "GEMINI_API_KEY": "your-api-key-here" } } } }

Claude Code uses a different registration mechanism — it doesn't readclaude_desktop_config.json. Useclaude mcp addinstead:

claude mcp add -e GEMINI_API_KEY=your-api-key-here -s user gemini -- npx -y @houtini/gemini-mcp

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

Verify withclaude mcp get gemini— you should seeStatus: Connected.

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 answering, so you get current information rather than training cutoff answers. Sources come back as markdown links. For questions where you want pure reasoning — "explain this code" or similar — setgrounding: false.

Supportsthinking_levelon Gemini 3 models:highfor maximum reasoning depth,lowto keep it fast,medium/minimalon Gemini 3 Flash only.

Use gemini:gemini_deep_research with: research_question="What are the current approaches to AI agent memory management?" max_iterations=5

Runs multiple grounded search iterations then synthesises a full report. Takes 2-5 minutes depending on complexity — worth it for anything needing comprehensive coverage rather than a quick answer.

Setmax_iterationsto 3-4 in Claude Desktop (4-minute tool timeout). In IDEs (Cursor, Windsurf, VS Code) or agent frameworks, 7-10 iterations produces noticeably better synthesis. Passfocus_areasas an array to steer toward specific angles.

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 isgemini-3-pro-image-preview(Nano Banana Pro). Also supportsgemini-2.5-flash-imagefor faster generation.

Whenuse_search=true, Gemini searches Google for current data before generating. Financial and news queries work reliably. The full-resolution image saves to disk automatically — the inline preview is resized for transport but the original is untouched.

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

Uses Google's Veo 3.1 model. Generates 4-8 second videos at up to 4K with native synchronised audio. Processing takes 2-5 minutes — the tool polls automatically until ready.

- aspectRatio—16:9landscape or9:16portrait/vertical
- generateAudio— on by default, produces dialogue and sound effects matching the prompt
- sampleCount— generate up to 4 variations in one call
- seed— deterministic output across runs
- generateThumbnail— extracts a frame via ffmpeg (needs ffmpeg in PATH)
- firstFrameImage— animate from a starting image (image-to-video)

This is the one people underestimate. SVG output isn't just diagrams — it's production-ready vector graphics you can drop straight into a codebase, a presentation, or a web page. Clean, scalable, no raster artefacts.

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

The output is actual SVG code — edit it, animate it, embed it in HTML, commit it to a repo. No rasterising, no export steps, no Figma required.

Conversational editing— Gemini 3 Pro Image maintains context across editing turns. Pass thought signatures back on subsequentedit_imagecalls for full continuity:

Use gemini:edit_image with: prompt="Change the colour scheme to blue and green" images=[{data: imageBase64, mimeType: "image/png", thoughtSignature: "fromPreviousCall"}]

Analysis— two tools for different purposes:

- describe_image— Fast general descriptions using Gemini 3 Flash
- analyze_image— Structured extraction and detailed reasoning using Gemini 3.1 Pro

Use gemini:load_image_from_path with filePath="C:/screenshots/error.png"

Reduce token usage by up to 75% whilst maintaining quality for the task:

For PDF OCR, MEDIUM gives identical text extraction quality to HIGH at half the tokens.

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"]

Returns a self-contained HTML file — inline CSS and vanilla JS, no external dependencies. Styles:minimal,bold,corporate,startup.

gemini_prompt_assistantincludes 9 professional chart design systems:

Use gemini:gemini_help with topic="overview"

Full documentation without leaving Claude. Topics:overview,image_generation,image_editing,image_analysis,chat,deep_research,grounding,media_resolution,models,all.

By default, images return as inline previews rendered directly in Claude. SetGEMINI_IMAGE_OUTPUT_DIRto auto-save everything:

"env": { "GEMINI_API_KEY": "your-api-key-here", "GEMINI_IMAGE_OUTPUT_DIR": "C:/Users/username/Pictures/gemini-output" }

The server uses a two-tier approach to handle the MCP protocol's 1MB JSON-RPC limit whilst preserving full-resolution files:

Gemini returns 2-5MB images. The resize is smart — it measures the non-image overhead in each response and calculates the exact binary budget available, stepping down dimensions (800→600→400→300→200px) until it fits. The full image is always there on disk.

Gemini 3 notes:Temperature is forced to 1.0 on Gemini 3 models (Google's requirement — lower values cause looping). Thinking level only applies togemini_chat.

Token budgets:max_tokensdefaults 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: unused headroom costs nothing. Values below 4,096 are ignored (Gemini 3 thinking burns tiny budgets before any visible output, which looks like a timeout) and values above the model's real limit are clamped.

- Node.js 18+
- A Gemini API key fromGoogle AI Studio
- ffmpeg (optional, for video thumbnail extraction)

Integrates with Jina AI APIs for web reading, search, and fact-checking.