# 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**.

![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)
![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)
![MCP](https://img.shields.io/badge/MCP-compatible-6E56CF.svg)

<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/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:

```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 © deepzhun (深准). Contributions welcome — open an issue or PR.