GitHub Stats

    Stars

    121

    Forks

    15

    Release Date

    5/23/2025

    about a month ago

    Detailed Description

    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

    Star History

    Star History

    Feb 4Feb 10Feb 16Feb 25Mar 2Mar 11Mar 22Apr 18May 16Jun 26Jul 603570105140
    Powered by MSeeP Analytics

    About the Project

    This app has not been claimed by its owner yet.

    Claim Ownership

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.