Image Generation MCP Server

An MCP (Model Context Protocol) server implementation for generating images using Replicate's black-forest-labs/flux-schnell model.

Ideally to be used with Cursor's MCP feature, but can be used with any MCP client.

Features

• Generate images from text prompts
• Configurable image parameters (resolution, aspect ratio, quality)
• Save generated images to specified directory
• Full MCP protocol compliance
• Error handling and validation

Prerequisites

• Node.js 16+
• Replicate API token
• TypeScript SDK for MCP

Setup

1. Clone the repository

2. Install dependencies:

   npm install
   

3. Add your Replicate API token directly in the code at src/imageService.ts by updating the apiToken constant:

   // No environment variables are used since they can't be easily set in cursor
   const apiToken = "your-replicate-api-token-here";
   

   Note: If using with Claude, you can create a .env file in the root directory and set your API token there:

   REPLICATE_API_TOKEN=your-replicate-api-token-here
   

   Then build the project:

   npm run build
   

Usage

To use with cursor:

1. Go to Settings
2. Select Features
3. Scroll down to "MCP Servers"
4. Click "Add new MCP Server"
5. Set Type to "Command"
6. Set Command to: node ./path/to/dist/server.js

API Parameters

Parameter	Type	Required	Default	Description
prompt	string	Yes	-	Text prompt for image generation
output_dir	string	Yes	-	Server directory path to save generated images
go_fast	boolean	No	false	Enable faster generation mode
megapixels	string	No	"1"	Resolution quality ("1", "2", "4")
num_outputs	number	No	1	Number of images to generate (1-4)
aspect_ratio	string	No	"1:1"	Aspect ratio ("1:1", "4:3", "16:9")
output_format	string	No	"webp"	Image format ("webp", "png", "jpeg")
output_quality	number	No	80	Compression quality (1-100)
num_inference_steps	number	No	4	Number of denoising steps (4-20)

Example Request

{
  "prompt": "black forest gateau cake spelling out 'FLUX SCHNELL'",
  "output_dir": "/var/output/images",
  "filename": "black_forest_cake",
  "output_format": "webp"
  "go_fast": true,
  "megapixels": "1",
  "num_outputs": 2,
  "aspect_ratio": "1:1"
}

Example Response

{
  "image_paths": [
    "/var/output/images/output_0.webp",
    "/var/output/images/output_1.webp"
  ],
  "metadata": {
    "model": "black-forest-labs/flux-schnell",
    "inference_time_ms": 2847
  }
}

Error Handling

The server handles the following error types:

• Validation errors (invalid parameters)
• API errors (Replicate API issues)
• Server errors (filesystem, permissions)
• Unknown errors (unexpected issues)

Each error response includes:

• Error code
• Human-readable message
• Detailed error information

License

ISC