Image Generation MCP Server

View original on GitHub

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

Clone the repository
Install dependencies:
```
npm install
```
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:

Go to Settings
Select Features
Scroll down to “MCP Servers”
Click “Add new MCP Server”
Set Type to “Command”
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