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

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

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

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

false

Enable faster generation mode

megapixels

string

"1"

Resolution quality ("1", "2", "4")

num_outputs

number

Number of images to generate (1-4)

aspect_ratio

string

"1:1"

Aspect ratio ("1:1", "4:3", "16:9")

output_format

string

"webp"

Image format ("webp", "png", "jpeg")

output_quality

number

Compression quality (1-100)

num_inference_steps

number

Number of denoising steps (4-20)

{ "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" }

{ "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 } }