# GenImgMCP 🎨

Local **MCP (Model Context Protocol)** server for image generation and editing using the `google/gemini-3.1-flash-image` model via **OpenRouter**.

Designed specifically for **coding agents** (such as Antigravity, Claude Code, Cursor, and other MCP clients), saving images directly to the project's local file system and returning the file path and structured metadata in a lightweight manner (without cluttering the context window with Base64 strings).

---

## ✨ Features

- 🖼️ **Image Generation (`generate_image`)**: Create images from detailed text prompts.
- 🖌️ **Image Editing and Variations (`edit_image`)**: Transform, refine, or add elements to existing images on disk.
- 💾 **Automatic Local Saving**: Saves image files directly to the project directory requested by the agent (or in `./generated_images/`).
- ⚡ **Lightweight & Efficient Response**: Returns only the absolute file path and metadata (size, format, aspect ratio), preserving the caller LLM's context tokens.
- 📐 **Aspect Ratio & Format Control**: Supports multiple aspect ratios (`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`) and file formats (`png`, `webp`, `jpeg`).
- 🔄 **Model Flexibility**: Defaults to `google/gemini-3.1-flash-image`, with support for any multimodal model available on OpenRouter.

---

## 🚀 Installation and Build

### 1. Prerequisites
- Node.js 18 or higher
- [OpenRouter](https://openrouter.ai/keys) API Key

### 2. Install Dependencies and Build

```bash
# In the project root:
npm install
npm run build
```

---

## ⚙️ Configuration

You can configure the API key in one of three ways:

1. **Environment Variable**: Set `OPENROUTER_API_KEY` in your environment.
2. **`.env` File**: Create a `.env` file in the root of the project:
   ```env
   OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   DEFAULT_IMAGE_MODEL=google/gemini-3.1-flash-image
   DEFAULT_OUTPUT_DIR=./generated_images
   ```
3. **Command Line Argument**: Pass `--api-key <your_key>` in arguments when starting the server.

---

## 🛠️ Available Tools

### 1. `generate_image`
Generates a new image based on a text prompt.

| Parameter | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `prompt` | `string` | **Yes** | Detailed description of the image to generate. |
| `output_path` | `string` | No | File path where the image will be saved (e.g., `./assets/banner.png`). |
| `aspect_ratio` | `string` | No | Aspect ratio of the image (`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`). Default: `1:1`. |
| `output_format`| `string` | No | File format (`png`, `webp`, `jpeg`). Default: `png`. |
| `model` | `string` | No | Model on OpenRouter (Default: `google/gemini-3.1-flash-image`). |

### 2. `edit_image`
Modifies an existing image provided by local file path.

| Parameter | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `image_path` | `string` | **Yes** | Source image path (e.g., `./assets/logo.png`) or Data URL. |
| `prompt` | `string` | **Yes** | Modification instructions or elements to add. |
| `output_path` | `string` | No | Destination path for the edited image. |
| `aspect_ratio` | `string` | No | Desired aspect ratio for the resulting image. |
| `output_format`| `string` | No | Output file format (`png`, `webp`, `jpeg`). |
| `model` | `string` | No | Model on OpenRouter (Default: `google/gemini-3.1-flash-image`). |

---

## 🔌 How to Integrate with MCP Clients

### Configuration in Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "genimg": {
      "command": "node",
      "args": [
        "D:/MyProjs.Github/GenImgMCP/dist/index.js"
      ],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
      }
    }
  }
}
```

### Configuration in Antigravity / Cursor / MCP Config (`mcp_config.json`)

```json
{
  "mcpServers": {
    "genimg": {
      "command": "node",
      "args": [
        "D:/MyProjs.Github/GenImgMCP/dist/index.js"
      ],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
      }
    }
  }
}
```

---

## 🧪 Testing the Server Locally

You can run the server directly in the terminal to verify startup:

```bash
node dist/index.js
```
*The server will start and wait for JSON-RPC messages on the stdio channel.*

---

## 📄 License

MIT