levisnkyyyy-images-mcp/README.md

Model Context Protocol server for AI image and video generation using LiteLLM and fal.ai

# images-mcp

Model Context Protocol server for AI image and video generation using LiteLLM and fal.ai.

## Features

- **Image Generation**: Generate images from text prompts using various AI models
- **Image Editing**: Edit existing images with masks and prompts
- **Video Generation**: Generate videos from text prompts using Veo3
- **Multiple Models**: Support for OpenAI DALL-E, Google Imagen (3.0, 4.0, 4.0 Ultra), and fal.ai models (Flux Pro, Flux Max)
- **Flexible Sizing**: Generate images in various sizes up to 4096x4096
- **Batch Generation**: Generate multiple images at once (1-4 images)

## Installation

```bash
npm install -g images-mcp
```

## Configuration

The server requires LiteLLM and/or fal.ai to be configured. Set the following environment variables:

- `LITELLM_URL`: URL of your LiteLLM instance (default: `http://litellm:4000`)
- `LITELLM_KEY`: API key for LiteLLM authentication (optional)
- `FAL_API_KEY`: API key for fal.ai models (required for Flux Pro, Flux Max, and Veo3)

## Usage

### As an MCP Server

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "images": {
      "command": "images-mcp",
      "env": {
        "LITELLM_URL": "http://your-litellm-instance:4000",
        "LITELLM_KEY": "your-api-key",
        "FAL_API_KEY": "your-fal-api-key"
      }
    }
  }
}
```

### Available Tools

#### image_generation

Generate images from text prompts.

**Parameters:**
- `prompt` (required): Text description of the image to generate
- `project_folder` (required): Path to the folder where generated images will be saved
- `image_name` (required): Base filename for the generated image(s) (without extension)
- `model` (optional): Model to use (default: "gpt-image-1-openai")
- `size` (optional): Image size - "256x256", "512x512", or "1024x1024" (default: "1024x1024")
- `n` (optional): Number of images to generate, 1-4 (default: 1)

**Example:**
```json
{
  "tool": "image_generation",
  "arguments": {
    "prompt": "A serene mountain landscape at sunset",
    "project_folder": "/home/user/images",
    "image_name": "mountain_sunset",
    "size": "1024x1024",
    "n": 2
  }
}
```

This will save images as:
- `/home/user/images/mountain_sunset_1.png`
- `/home/user/images/mountain_sunset_2.png`

#### image_edit

Edit existing images based on prompts and optional masks.

**Parameters:**
- `image_path` (required): Full path to the image file to edit
- `prompt` (required): Text description of how to edit the image
- `project_folder` (required): Path to the folder where edited images will be saved
- `image_name` (required): Base filename for the edited image(s) (without extension)
- `mask` (optional): Base64 encoded mask indicating areas to edit
- `model` (optional): Model to use (default: "gpt-image-1-openai")
- `size` (optional): Output image size (default: "1024x1024")
- `n` (optional): Number of edited versions to generate, 1-4 (default: 1)

**Example:**
```json
{
  "tool": "image_edit",
  "arguments": {
    "image_path": "/home/user/images/landscape.png",
    "prompt": "Add a rainbow in the sky",
    "project_folder": "/home/user/images/edited",
    "image_name": "landscape_with_rainbow",
    "mask": "base64_encoded_mask_data"
  }
}
```

This will:
1. Read the image from `/home/user/images/landscape.png`
2. Apply the edits based on the prompt
3. Save the edited image as `/home/user/images/edited/landscape_with_rainbow.png`

## Development

```bash
# Clone the repository
git clone https://github.com/yourusername/images-mcp.git
cd images-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

## Requirements

- Node.js >= 16.0.0
- LiteLLM instance with image generation models configured

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.