@houtini/gemini-mcp

I've been running this 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 genuinely well. Having them as tools inside Claude beats switching browser tabs.

Thirteen tools. One npx command.

Quick Navigation

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

What it looks like

Generated images, SVGs, and videos render inline in Claude Desktop with zoom controls, file paths, and prompt context:

Image generation	SVG / diagram generation

Image embed	SVG embed	Video embed

Get started in two minutes

Step 1: Get a Gemini API key

Go to Google AI Studio 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.

Step 2: Add to your Claude Desktop config

Config file locations:

• Windows: C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

Step 3: Restart Claude Desktop

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

Local build instead

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 (CLI)

Claude Code uses a different registration mechanism — it doesn't read claude_desktop_config.json. Use claude mcp add instead:

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

With optional image output directory:

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 with claude mcp get gemini — you should see Status: Connected.

What it does

Chat with Google Search grounding

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 — set grounding: false.

Supports thinking_level on Gemini 3 models: `hig

... View full README on GitHub