MCP Image Generator

English | 中文版

A Model Context Protocol (MCP) server for image generation via Chat Completion API.

Supports image generation through models that return images via the standard OpenAI /v1/chat/completions interface (e.g., Gemini, GPT-4o), extracting base64-encoded images from the response content.

Features

• Single Image Generation: Generate individual images with customizable parameters
• Batch Image Generation: Generate up to 9 images at once
• Chat Completion Based: Works with models that generate images through the standard OpenAI Chat Completion interface
• OpenAI-Compatible: Works with any OpenAI-compatible API provider (ChatAnywhere, OpenAI, etc.)
• MCP Protocol: Fully implements the MCP specification for seamless integration
• TypeScript: Written in TypeScript for type safety

Supported Models

This MCP server works with models that support image generation through the OpenAI Chat Completion interface:

| Provider | Model | Example | |----------|-------|---------| | ChatAnywhere | Gemini | gemini-3.1-flash-image-preview | | ChatAnywhere | GPT-4o | gpt-4o | | OpenAI | GPT-4o | gpt-4o | | Google AI Studio | Gemini 2.0 | gemini-2.0-flash |

Any OpenAI-compatible API provider that supports image generation via /v1/chat/completions should work.

Installation

npm install
npm run build

Configuration

Required Environment Variables

| Variable | Description | Example | |-----------|-------------|----------| | API_KEY | API key for the image generation service | sk-xxxxx | | BASE_URL | Base URL of the OpenAI-compatible API | https://api.chatanywhere.tech/v1 | | DEFAULT_MODEL | Default model for image generation | gemini-3.1-flash-image-preview |

MCP Client Configuration (Claude Desktop)

{
  "mcpServers": {
    "yifan-image-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@yifanfeng97/mcp-image-generator"
      ],
      "env": {
        "API_KEY": "your-api-key-here",
        "BASE_URL": "https://api.chatanywhere.tech/v1",
        "DEFAULT_MODEL": "gemini-3.1-flash-image-preview"
      }
    }
  }
}

Usage

Tools

generate_image

Generate a single image.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | prompt | string | Yes | - | Image generation prompt | | output_path | string | Yes | - | Local file path to save the image | | model | string | No | DEFAULT_MODEL env | Model name | | output_format | string | No | png | Format: png, jpeg, webp | | size | string | No | 1024x1024 | Image size |

Example:

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A cute cat",
    "output_path": "./my_cat.png"
  }
}

batch_generate_images

Generate multiple images (up to 9).

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | prompts | string[] | Yes | - | Array of prompts (max 9) | | output_dir | string | Yes | - | Directory to save images | | model | string | No | DEFAULT_MODEL env | Model name | | output_format | string | No | png | Format | | size | string | No | 1024x1024 | Image size |

Example:

{
  "name": "batch_generate_images",
  "arguments": {
    "prompts": ["A red apple", "A green apple"],
    "output_dir": "./generated_images"
  }
}

Supported Image Sizes

| Size | Dimensions | Use Case | |------|------------|----------| | 256x256 | 256×256 | Thumbnails, icons | | 512x512 | 512×512 | Social avatars | | 1024x1024 | 1024×1024 | General purpose (default) | | 1024x1792 | 1024×1792 | Vertical posters | | 1792x1024 | 1792×1024 | Horizontal posters |

Manual Testing Scripts

Test the MCP server with real API calls:

Single Image Test

npx tsx scripts/test-single-image.ts

Batch Images Test

npx tsx scripts/test-batch-images.ts

For detailed configuration and troubleshooting, see scripts/README.md.

Development

# Build
npm run build

# Run
npm start

# Development mode
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

# Test (Jest)
npm test

Project Structure

src/
├── index.ts                      # Entry point
├── server.ts                     # MCP server
├── tools/
│   ├── generate_image.ts         # Single image tool
│   └── batch_generate_images.ts  # Batch images tool
├── services/
│   └── image_processor.ts        # Image utilities
├── types/
│   └── index.ts                # Type definitions
└── utils/
    ├── config.ts                # Config management
    └── validators.ts            # Parameter validation

tests/                           # Jest tests
scripts/                        # Manual test scripts
dist/                           # Build output

API Providers

Works with any OpenAI-compatible API:

• ChatAnywhere: https://api.chatanywhere.tech
• OpenAI: https://api.openai.com/v1

Error Handling

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

Error Codes

| Code | Description | |------|-------------| | MISSING_API_KEY | API_KEY env variable not set | | MISSING_BASE_URL | BASE_URL env variable not set | | MISSING_DEFAULT_MODEL | DEFAULT_MODEL env variable not set | | API_ERROR | General API error | | IMAGE_EXTRACTION_FAILED | Failed to extract image from response | | VALIDATION_ERROR | Invalid parameters |

License

MIT