\n\n# Gemini MCP - Google Gemini image generation, video and search grounding inside Claude\n\n[](https://www.npmjs.com/package/@houtini/gemini-mcp)\n[](https://registry.modelcontextprotocol.io)\n[](https://snyk.io/test/github/houtini-ai/gemini-mcp)\n[](https://opensource.org/licenses/Apache-2.0)\n\nI'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.\n\nThirteen tools, covering the models people actually come looking for: **Nano Banana Pro** (`gemini-3-pro-image-preview`) for image generation, **Veo 3.1** for video with synchronised audio, and **Gemini 3.1 Pro** for 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.\n\nOne `npx` command.\n\n
\n\n---\n\n> **Quick Navigation**\n>\n> [Get started](#get-started-in-two-minutes) | [What it does](#what-it-does) | [SVG generation](#svg-generation) | [Image output](#image-output-and-storage) | [Configuration](#configuration-reference) | [Tools](#tools-reference) | [Models](#model-reference) | [Requirements](#requirements)\n\n---\n\n## What it looks like\n\nGenerated images, SVGs, and videos render inline in Claude Desktop with zoom controls, file paths, and prompt context:\n\n| Image generation | SVG / diagram generation |\n|:---:|:---:|\n|  |  |\n\n| Image embed | SVG embed | Video embed |\n|:---:|:---:|:---:|\n|  |  |  |\n\n---\n\n## Get started in two minutes\n\n**Step 1: Get a Gemini API key**\n\nGo to [Google AI Studio](https://aistudio.google.com/apikey) and 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.\n\n**Step 2: Add to your Claude Desktop config**\n\nConfig file locations:\n- Windows: `C:\\Users\\{username}\\AppData\\Roaming\\Claude\\claude_desktop_config.json`\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"gemini\": {\n \"command\": \"npx\",\n \"args\": [\"@houtini/gemini-mcp\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n**Step 3: Restart Claude Desktop**\n\nThat's it. Tools show up automatically. `npx` pulls the package on first run — no separate install needed.\n\n\n### Local build instead\n\nFor development, or if you'd rather not rely on npx:\n\n```bash\ngit clone https://github.com/houtini-ai/gemini-mcp\ncd gemini-mcp\nnpm install --include=dev\nnpm run build\n```\n\nThen point your config at the local build:\n\n```json\n{\n \"mcpServers\": {\n \"gemini\": {\n \"command\": \"node\",\n \"args\": [\"C:/path/to/gemini-mcp/dist/index.js\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n### Claude Code (CLI)\n\nClaude Code uses a different registration mechanism — it doesn't read `claude_desktop_config.json`. Use `claude mcp add` instead:\n\n```bash\nclaude mcp add -e GEMINI_API_KEY=your-api-key-here -s user gemini -- npx -y @houtini/gemini-mcp\n```\n\nWith optional image output directory:\n\n```bash\nclaude mcp add \\\n -e GEMINI_API_KEY=your-api-key-here \\\n -e GEMINI_IMAGE_OUTPUT_DIR=/path/to/output \\\n -s user \\\n gemini -- npx -y @houtini/gemini-mcp\n```\n\nVerify with `claude mcp get gemini` — you should see `Status: Connected`.\n\n---\n\n## What it does\n\n### Chat with Google Search grounding\n\n```\nUse gemini:gemini_chat to ask: \"What changed in the MCP spec in the last month?\"\n```\n\nGrounding 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 — set `grounding: false`.\n\nSupports `thinking_level` on Gemini 3 models: `high` for maximum reasoning depth, `low` to keep it fast, `medium`/`minimal` on Gemini 3 Flash only.\n\n### Deep research\n\n```\nUse gemini:gemini_deep_research with:\n research_question=\"What are the current approaches to AI agent memory management?\"\n max_iterations=5\n```\n\nRuns 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.\n\nSet `max_iterations` to 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. Pass `focus_areas` as an array to steer toward specific angles.\n\n\n### Image generation with search grounding\n\n```\nUse gemini:generate_image with:\n prompt=\"Stock price chart showing Apple (AAPL) closing prices for the last 5 trading days\"\n use_search=true\n aspectRatio=\"16:9\"\n```\n\nDefault model is `gemini-3-pro-image-preview` (Nano Banana Pro). Also supports `gemini-2.5-flash-image` for faster generation.\n\nWhen `use_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.\n\n### Video generation with Veo 3.1\n\n```\nUse gemini:generate_video with:\n prompt=\"A close-up shot of a futuristic coffee machine brewing a glowing blue espresso, steam rising dramatically. Cinematic lighting.\"\n resolution=\"1080p\"\n durationSeconds=8\n```\n\nUses 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.\n\nOptions worth knowing:\n- `aspectRatio` — `16:9` landscape or `9:16` portrait/vertical\n- `generateAudio` — on by default, produces dialogue and sound effects matching the prompt\n- `sampleCount` — generate up to 4 variations in one call\n- `seed` — deterministic output across runs\n- `generateThumbnail` — extracts a frame via ffmpeg (needs ffmpeg in PATH)\n- `firstFrameImage` — animate from a starting image (image-to-video)\n\n\n### SVG generation\n\nThis 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.\n\n```\nUse gemini:generate_svg with:\n prompt=\"Architecture diagram showing a microservices system with API gateway, three services, and a shared database\"\n style=\"technical\"\n width=1000\n height=600\n```\n\nFour styles:\n\n| Style | Best for |\n|-------|----------|\n| `technical` | Architecture diagrams, flowcharts, system maps |\n| `artistic` | Illustrations, decorative graphics, icons |\n| `minimal` | Clean data visualisations, simple charts |\n| `data-viz` | Complex charts, dashboards, infographics |\n\nThe 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.\n\n\n\n### Image editing and analysis\n\n**Conversational editing** — Gemini 3 Pro Image maintains context across editing turns. Pass thought signatures back on subsequent `edit_image` calls for full continuity:\n\n```\nUse gemini:edit_image with:\n prompt=\"Change the colour scheme to blue and green\"\n images=[{data: imageBase64, mimeType: \"image/png\", thoughtSignature: \"fromPreviousCall\"}]\n```\n\n**Analysis** — two tools for different purposes:\n- `describe_image` — Fast general descriptions using Gemini 3 Flash\n- `analyze_image` — Structured extraction and detailed reasoning using Gemini 3.1 Pro\n\n**Load local files:**\n```\nUse gemini:load_image_from_path with filePath=\"C:/screenshots/error.png\"\n```\n\n### Media resolution control\n\nReduce token usage by up to 75% whilst maintaining quality for the task:\n\n| Level | Tokens | Savings | Best for |\n|-------|--------|---------|----------|\n| `MEDIA_RESOLUTION_LOW` | 280 | 75% | Simple tasks, bulk operations |\n| `MEDIA_RESOLUTION_MEDIUM` | 560 | 50% | PDFs/documents (OCR saturates here) |\n| `MEDIA_RESOLUTION_HIGH` | 1120 | default | Detailed analysis |\n| `MEDIA_RESOLUTION_ULTRA_HIGH` | 2000+ | per-image only | Maximum detail |\n\nFor PDF OCR, MEDIUM gives identical text extraction quality to HIGH at half the tokens.\n\n\n### Landing page generation\n\n```\nUse gemini:generate_landing_page with:\n brief=\"A SaaS tool that helps developers monitor API latency\"\n companyName=\"PingWatch\"\n primaryColour=\"#6366F1\"\n style=\"startup\"\n sections=[\"hero\", \"features\", \"pricing\", \"cta\"]\n```\n\nReturns a self-contained HTML file — inline CSS and vanilla JS, no external dependencies. Styles: `minimal`, `bold`, `corporate`, `startup`.\n\n### Professional chart design systems\n\n`gemini_prompt_assistant` includes 9 professional chart design systems:\n\n| System | Inspiration | Best for |\n|--------|------------|----------|\n| **storytelling** | Cole Nussbaumer Knaflic | Executive presentations |\n| **financial** | Financial Times | Editorial journalism — FT Pink, serif titles |\n| **terminal** | Bloomberg / Fintech | High-density dark mode with neon |\n| **modernist** | W.E.B. Du Bois | Bold geometric blocks, stark contrasts |\n| **professional** | IBM Carbon / Tailwind | Enterprise dashboards |\n| **editorial** | FiveThirtyEight / Economist | Data journalism |\n| **scientific** | Nature / Science | Academic rigour |\n| **minimal** | Edward Tufte | Maximum data-ink ratio |\n| **dark** | Observable | Modern dark mode |\n\n### Help system\n\n```\nUse gemini:gemini_help with topic=\"overview\"\n```\n\nFull documentation without leaving Claude. Topics: `overview`, `image_generation`, `image_editing`, `image_analysis`, `chat`, `deep_research`, `grounding`, `media_resolution`, `models`, `all`.\n\n---\n\n## Image output and storage\n\nBy default, images return as inline previews rendered directly in Claude. Set `GEMINI_IMAGE_OUTPUT_DIR` to auto-save everything:\n\n```json\n\"env\": {\n \"GEMINI_API_KEY\": \"your-api-key-here\",\n \"GEMINI_IMAGE_OUTPUT_DIR\": \"C:/Users/username/Pictures/gemini-output\"\n}\n```\n\nThe server uses a two-tier approach to handle the MCP protocol's 1MB JSON-RPC limit whilst preserving full-resolution files:\n\n| Tier | Purpose |\n|------|---------|\n| **Full-res** | Saved to disk immediately, untouched |\n| **Preview** | Resized JPEG for inline transport — dynamically sized to fit under the cap |\n\nGemini 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.\n\n---\n\n## Configuration reference\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `GEMINI_API_KEY` | Yes | — | Google AI API key from [AI Studio](https://aistudio.google.com/apikey) |\n| `GEMINI_DEFAULT_MODEL` | No | `gemini-3.1-pro-preview` | Default model for `gemini_chat` and `analyze_image` |\n| `GEMINI_DEFAULT_GROUNDING` | No | `true` | Enable Google Search grounding by default |\n| `GEMINI_IMAGE_OUTPUT_DIR` | No | — | Auto-save directory for generated images and videos |\n| `GEMINI_ALLOW_EXPERIMENTAL` | No | `false` | Include experimental/preview models in auto-discovery |\n| `GEMINI_MCP_LOG_FILE` | No | `false` | Write logs to `~/.gemini-mcp/logs/` |\n| `DEBUG_MCP` | No | `false` | Log to stderr for debugging tool calls |\n\n\n## Tools reference\n\n| Tool | Description |\n|------|-------------|\n| `gemini_chat` | Chat with Gemini 3.1 Pro. Google Search grounding on by default. Supports `thinking_level` |\n| `gemini_deep_research` | Multi-step iterative research with Google Search. Synthesises comprehensive reports |\n| `gemini_list_models` | Lists available models from the Gemini API |\n| `gemini_help` | Documentation for all features without leaving Claude |\n| `gemini_prompt_assistant` | Expert guidance for image generation with 9 chart design systems |\n| `generate_image` | Image generation with optional search grounding. Full-res saved to disk |\n| `edit_image` | Edit images with natural-language instructions. Multi-turn continuity via thought signatures |\n| `describe_image` | Fast image descriptions using Gemini 3 Flash |\n| `analyze_image` | Structured extraction and analysis using Gemini 3.1 Pro |\n| `load_image_from_path` | Read a local image file and return base64 for any image tool |\n| `generate_video` | Video generation with Veo 3.1 — 4-8 seconds at up to 4K with native audio |\n| `generate_svg` | Production-ready SVG: diagrams, illustrations, icons, data visualisations |\n| `generate_landing_page` | Self-contained HTML landing pages with inline CSS/JS |\n\n---\n\n## Model reference\n\n| Model | Used by | Notes |\n|-------|---------|-------|\n| `gemini-3.1-pro-preview` | `gemini_chat`, `analyze_image` | Default. Advanced reasoning |\n| `gemini-3-pro-image-preview` | `generate_image`, `edit_image` | Nano Banana Pro — highest quality image generation |\n| `gemini-2.5-flash-image` | `generate_image` (optional) | Faster generation, higher volume |\n| `gemini-3-flash-preview` | `describe_image` | Fast general descriptions |\n| `veo-3.1-generate-preview` | `generate_video` | Veo 3.1 — 4K video with native audio |\n\n**Gemini 3 notes:** Temperature is forced to 1.0 on Gemini 3 models (Google's requirement — lower values cause looping). Thinking level only applies to `gemini_chat`.\n\n**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: 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.\n\n---\n\n## Requirements\n\n- Node.js 18+\n- A Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey)\n- ffmpeg (optional, for video thumbnail extraction)\n\n## Licence\n\nApache-2.0\n",
"bytes": 15330,
"sha": "5fda2e9995ebee36f7698fc344fa177596b38d56969ed990cfb2a1439d3987c5",
"repo_slug": "houtini-ai/gemini-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_houtini_ai_gemini_8ec207f9/readme"
}
![\"Gemini](\"https://raw.githubusercontent.com/houtini-ai/gemini-mcp/main/assets/logo.png\"){kind=logo}
\n