# Gemini Image Generation MCP Server

A Model Context Protocol (MCP) server that provides image generation capabilities using Google's Gemini 2.0 Flash Preview model. This server allows AI assistants to generate high-quality images from text prompts through the MCP protocol.

## Features

- **Image Generation**: Generate images from text prompts using Gemini 2.0 Flash Preview
- **Multiple Output Formats**: Support for PNG, JPEG, and other image formats
- **File Management**: Automatic saving of generated images with organized file naming
- **Base64 Support**: Handle image data in base64 format for easy integration
- **Status Monitoring**: Check API connection status and model information
- **Prompt Templates**: Pre-built prompts for optimized image generation

## Prerequisites

- Python 3.9 or higher
- Google AI API key (Gemini API access)
- uv package manager (recommended) or pip

## Installation

### Using uv (Recommended)

1. Clone or download this repository:
```bash
git clone <repository-url>
cd image-generation-gemini-mcp
```

2. Install dependencies:
```bash
uv sync
```

### Using pip

1. Install dependencies:
```bash
pip install -r requirements.txt
```

## Setup

### 1. Get Google AI API Key

1. Visit [Google AI Studio](https://aistudio.google.com/)
2. Create a new API key
3. Copy the API key for use in the next step

### 2. Set Environment Variable

Set your Gemini API key as an environment variable:

**Windows (PowerShell):**
```powershell
$env:GEMINI_API_KEY="your-api-key-here"
```

**Windows (Command Prompt):**
```cmd
set GEMINI_API_KEY=your-api-key-here
```

**macOS/Linux:**
```bash
export GEMINI_API_KEY="your-api-key-here"
```

For permanent setup, add the environment variable to your system's environment variables or shell profile.

## Usage

### Running the Server

#### Development Mode
To test the server locally:
```bash
uv run server.py
```

#### MCP Integration Mode
To run as an MCP server:
```bash
uv run server.py stdio
```

### Integration with MCP Clients

#### Claude Desktop Integration

1. Add the server to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "gemini-image-generator": {
      "command": "uv",
      "args": ["run", "server.py", "stdio"],
      "cwd": "C:\\path\\to\\image-generation-gemini-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

2. Restart Claude Desktop
3. The image generation tools will be available in your conversations

#### Other MCP Clients

For other MCP-compatible clients, configure them to run:
```bash
uv run server.py stdio
```

With the working directory set to this project folder and the `GEMINI_API_KEY` environment variable configured.

## Available Tools

### `generate_image`
Generate an image from a text prompt.

**Parameters:**
- `prompt` (string): Text description of the image to generate
- `output_dir` (string, optional): Directory to save the image (default: "./generated_images")

**Returns:**
- `success` (boolean): Whether generation was successful
- `message` (string): Status message or error description
- `image_data` (string): Base64 encoded image data (if successful)
- `mime_type` (string): MIME type of the generated image
- `file_extension` (string): File extension for the image

### `save_image_from_base64`
Save a base64 encoded image to a file.

**Parameters:**
- `image_data` (string): Base64 encoded image data
- `filename` (string): Name for the output file (include extension)
- `output_dir` (string, optional): Directory to save the image

**Returns:**
- `success` (string): "true" or "false"
- `message` (string): Status message
- `file_path` (string): Path to saved file (if successful)

## Available Resources

### `gemini://api-status`
Check the status of the Gemini API connection.

### `gemini://model-info`
Get information about the Gemini image generation model capabilities.

## Available Prompts

### `image_generation_prompt`
Generate a detailed prompt optimized for image generation.

**Parameters:**
- `subject` (string): Main subject or object to generate
- `style` (string, optional): Art style (default: "photorealistic")
- `mood` (string, optional): Mood or atmosphere (default: "neutral")

## Example Usage

Once integrated with an MCP client like Claude Desktop, you can:

1. **Generate an image:**
   ```
   Please generate an image of a sunset over mountains
   ```

2. **Use specific styles:**
   ```
   Create a cartoon-style image of a friendly robot
   ```

3. **Check API status:**
   ```
   Can you check the status of the Gemini API?
   ```

4. **Get model information:**
   ```
   What are the capabilities of the image generation model?
   ```

## File Structure

```
image-generation-gemini-mcp/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── pyproject.toml        # Project configuration
├── README.md             # This file
├── docs/                 # Documentation files
│   ├── development-guidelines.md
│   ├── mcp-info.md
│   └── mcp-python-sdk-readme.md
└── generated_images/     # Default output directory (created automatically)
```

## Troubleshooting

### Common Issues

1. **"GEMINI_API_KEY environment variable is required"**
   - Ensure you've set the `GEMINI_API_KEY` environment variable
   - Verify the API key is valid and has access to Gemini API

2. **"Error connecting to Gemini API"**
   - Check your internet connection
   - Verify your API key is correct and active
   - Ensure you have access to the Gemini 2.0 Flash Preview model

3. **"No image was generated"**
   - Try rephrasing your prompt
   - Ensure your prompt is descriptive and clear
   - Check if there are any content policy restrictions

4. **Permission errors when saving files**
   - Ensure the output directory is writable
   - Check file system permissions

### Getting Help

- Check the [MCP documentation](https://modelcontextprotocol.io/)
- Review the [Google AI documentation](https://ai.google.dev/)
- Ensure all dependencies are properly installed

## Development

### Code Quality

This project follows the MCP development guidelines:

- **Formatting:** `uv run ruff format .`
- **Linting:** `uv run ruff check .`
- **Type checking:** `uv run pyright`

### Testing

Run tests with:
```bash
uv run pytest
```

## License

This project is licensed under the MIT License. See the LICENSE file for details.

## Contributing

Contributions are welcome! Please follow the MCP development guidelines and ensure all code is properly formatted and type-checked before submitting.