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