# Gemini Design MCP Server

An MCP (Model Context Protocol) server that uses **Gemini 2.5 Flash** to generate frontend UI code. Works with Claude Code, Cursor, and any MCP-compatible client.

## Tools

| Tool | Description |
|------|-------------|
| `gemini_design` | Generate UI code from a text description |
| `gemini_screenshot_to_code` | Reproduce a UI from a screenshot image |
| `gemini_refine` | Iteratively refine existing code with edit instructions |

## Setup

### 1. Clone and install

```bash
git clone <repo-url>
cd mcp-design-gemini
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Add your Gemini API key

Create a `.env` file in the project root:

```
GEMINI_API_KEY=your_api_key_here
```

Get a free API key at [aistudio.google.com](https://aistudio.google.com/apikey).

### 3. Configure in Claude Code

Add this to your Claude Code MCP settings (`~/.claude/claude_code_config.json`):

```json
{
  "mcpServers": {
    "gemini-design": {
      "command": "/ABSOLUTE/PATH/TO/mcp-design-gemini/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/mcp-design-gemini/server.py"]
    }
  }
}
```

Replace `/ABSOLUTE/PATH/TO/` with the actual path on your machine.

### 4. Restart Claude Code

The server starts automatically when Claude Code calls any of its tools.

## Usage Examples

**Generate a UI:**
> "Design a pricing page for a SaaS product"

**Convert a screenshot:**
> "Convert this screenshot to code: /path/to/screenshot.png"

**Refine existing code:**
> "Change the background to dark blue and make the font bigger"

**Control token budget** (on `gemini_design`):
- `complexity: "small"` — 8K tokens (button, card)
- `complexity: "medium"` — 16K tokens (form, navbar)
- `complexity: "large"` — 32K tokens (full page, default)
- `complexity: "xl"` — 64K tokens (dashboard, multi-page)

## Features

- **Image compression** — Screenshots are auto-resized before sending to Gemini (saves 50-80% on input tokens)
- **Response caching** — Identical `gemini_design` prompts return instantly from cache
- **Dynamic token budget** — Match output size to component complexity
- **Iterative refinement** — Edit generated code without regenerating from scratch

## Requirements

- Python 3.10+
- A [Gemini API key](https://aistudio.google.com/apikey) (free tier works)