Gemini MCP Server

A small, clean Model Context Protocol server that connects any MCP client — Claude Desktop, Cursor, Cline, Cowork — to the Google Gemini API.

<p align="center"><img src="demo.gif" alt="gemini-mcp-server demo" width="760"></p>

One Python file, six tools, no framework lock-in. Bring your own Gemini key and you can generate text, hold multi-turn chats, understand images, embed text, and count tokens — straight from your assistant.

✨ Tools

Tool	What it does
gemini_generate	Single-turn text generation (system instruction, temperature, JSON mode)
gemini_chat	Multi-turn conversation with full history
gemini_vision	Analyze / OCR / describe an image (base64 + prompt)
gemini_embed	Text embeddings for search, clustering, RAG
gemini_count_tokens	Count tokens for cost & context-window planning
gemini_list_models	Discover available models and their limits

🚀 Quick start

Option A — one-click (Windows, Claude Desktop)

# in the repo folder, right-click install.ps1 -> "Run with PowerShell"
./install.ps1

It asks for your API key, installs dependencies, and wires up Claude Desktop. Restart Claude and you're done.

Option B — manual (any OS / any MCP client)

git clone https://github.com/deepzhun/gemini-mcp-server.git
cd gemini-mcp-server
pip install -r requirements.txt
export GEMINI_API_KEY="your-api-key"      # Windows: setx GEMINI_API_KEY "your-api-key"
python gemini_mcp.py

Get a free API key at https://ai.google.dev/gemini-api/docs/api-key.

🔌 Add to your MCP client

Copy config.example.json and drop the server block into your client config (Claude Desktop: claude_desktop_config.json), replacing the placeholder key:

{
  "mcpServers": {
    "gemini": {
      "command": "python",
      "args": ["/absolute/path/to/gemini_mcp.py"],
      "env": { "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE" }
    }
  }
}

💬 Usage examples

Once connected, just ask your assistant in natural language:

• "Use gemini to summarize this article in three bullet points."
• "Ask gemini-2.5-pro to refactor this function and explain the change."
• "Use gemini_vision to read the text in this screenshot."
• "Embed these 20 product descriptions with gemini for similarity search."

🔐 Security

• The key is read from the GEMINI_API_KEY (or GOOGLE_API_KEY) environment variable — never hard-code it.
• config.json and .env are git-ignored so a real key can't be committed by accident.
• Rotate your key at Google AI Studio if it is ever exposed.

🛠️ Development

pip install -r requirements.txt
python -c "import gemini_mcp; print(gemini_mcp.mcp.name)"   # smoke test

The whole server is a single file (gemini_mcp.py): typed Pydantic inputs, consistent error handling, and MCP tool annotations. Easy to read, easy to fork.

📄 License

MIT © deepzhun (深准). Contributions welcome — open an issue or PR.