# mcp-gemini-image

An MCP (Model Context Protocol) server that provides image generation capabilities using Google's Gemini 2.5 Flash Image Preview model.

## Features

- **Text-to-Image Generation**: Generate images from text prompts
- **Image-to-Image Generation**: Transform existing images with text guidance
- **Resource Management**: Access generated images through MCP resources
- **Automatic Cleanup**: Auto-deletes images older than 8 hours on startup
- **Security**: Built-in rate limiting, input validation, and file size limits

## Installation

### Prerequisites

You'll need a Google Gemini API key. Get one from [Google AI Studio](https://aistudio.google.com/app/apikey).

### Option 1: Install with Claude Code (Recommended)

1. Clone or download this repository to your local machine

2. Add the MCP server using the Claude CLI:

**macOS/Linux:**
```bash
claude mcp add mcp-gemini-image --env GEMINI_API_KEY=your-api-key-here \
  -- node /absolute/path/to/mcp-gemini-image/index.js
```

**Windows:**
```bash
claude mcp add mcp-gemini-image --env GEMINI_API_KEY=your-api-key-here -- cmd /c node C:\absolute\path\to\mcp-gemini-image\index.js
```

3. Restart Claude Code to load the server

**Note:** The `--` separator is required to separate Claude CLI flags from the server command.

### Option 2: Manual Configuration

Add this configuration to your Claude Desktop config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcp-gemini-image": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gemini-image/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Option 3: Install with Gemini Code Assist

1. Clone or download this repository to your local machine

2. Open your Gemini settings file:
   - **VS Code**: `~/.gemini/settings.json`
   - **IntelliJ**: Create `mcp.json` in your IDE's configuration directory

3. Add the server configuration:

```json
{
  "mcpServers": {
    "mcp-gemini-image": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gemini-image/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

4. Restart your IDE to load the MCP server

### Option 4: Install with OpenAI Codex

1. Clone or download this repository to your local machine

2. Open your Codex config file: `~/.codex/config.toml`

3. Add the server configuration:

```toml
[mcp_servers.mcp-gemini-image]
command = "node"
args = ["/absolute/path/to/mcp-gemini-image/index.js"]
env = { "GEMINI_API_KEY" = "your-api-key-here" }
```

4. Restart Codex to load the MCP server

### Option 5: Install from NPM (if published)

```bash
npm install -g mcp-gemini-image
```

Then configure in your MCP client:
```json
{
  "mcpServers": {
    "mcp-gemini-image": {
      "command": "mcp-gemini-image",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Usage

Once configured, the server provides two tools:

### `generate_image`

Generate an image from a text prompt.

**Parameters:**
- `prompt` (string, required): Text description of the image to generate
- `input_image` (string, optional): Base64-encoded input image for image-to-image generation
- `input_image_mime_type` (string, optional): MIME type of input image (default: "image/png")

**Example:**
```javascript
{
  "prompt": "A serene mountain landscape at sunset",
  "input_image": "base64encodeddata...",
  "input_image_mime_type": "image/jpeg"
}
```

### `cleanup_images`

Delete generated images based on age.

**Parameters:**
- `max_age_hours` (number, optional): Delete only images older than this many hours. If not specified, deletes all images.

**Example:**
```javascript
{
  "max_age_hours": 24
}
```

## Resources

Generated images are exposed as MCP resources with URIs in the format:
```
gemini-image:///<filename>
```

These resources can be read by MCP clients to access the generated images.

## Security Features

- **Rate Limiting**: 10 requests per minute
- **Input Validation**: Validates prompts and base64 data
- **File Size Limits**:
  - Generated images: 10MB max
  - Input images: 20MB max (base64)
  - Prompts: 10,000 characters max
- **Path Traversal Protection**: Validates all file paths
- **Extension Whitelist**: Only allows png, jpeg, jpg, webp, gif
- **Automatic Cleanup**: Removes images older than 8 hours on startup

## Development

Run the server directly:

```bash
npm start
```

The server uses stdio transport and is designed to be invoked by MCP clients.

## File Structure

```
.
├── index.js           # Main server implementation
├── package.json       # NPM configuration
├── .gitignore        # Excludes generated_images/
├── CLAUDE.md         # Claude Code guidance
└── generated_images/ # Auto-generated images (created automatically)
```

## Troubleshooting

### "GEMINI_API_KEY environment variable is required"

Make sure you've set the `GEMINI_API_KEY` environment variable in your MCP client configuration.

### "Rate limit exceeded"

The server limits requests to 10 per minute. Wait a moment before trying again.

### "Invalid or unsupported image type"

Only png, jpeg, jpg, webp, and gif formats are supported.

## License

MIT