Content
# Gemini MCP Server
> A small, clean [Model Context Protocol](https://modelcontextprotocol.io) 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)
```powershell
# 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)
```bash
git clone https://github.com/wilmalunsford1201-prog/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:
```json
{
"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](https://aistudio.google.com/apikey) if it is ever exposed.
## 🛠️ Development
```bash
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 © shenzhun (深准). Contributions welcome — open an issue or PR.
