sd-image-gen-mcp Server

A MCP server that provides text-to-image generation capabilities using Stable Diffusion WebUI API (ForgeUI/AUTOMATIC-1111). It also supports optional image uploading to a Cloudflare ImgBed instance.

Installation

Prerequisites

• Node.js (v18 or later recommended)
• npm
• Access to a Stable Diffusion WebUI instance with API enabled
• The WebUI must have --api flag enabled when starting
• (Optional) Access to a Cloudflare ImgBed instance for image hosting.

Setup

1. Clone the repository:

   git clone https://github.com/slot181/sd-image-gen-mcp.git
   cd sd-image-gen-mcp

2. Install dependencies:

   npm install

   This will install necessary packages including axios, sharp, and form-data.

3. Build the server:

   npm run build

4. Configure the server:

   You can configure the server using command-line arguments (-e KEY VALUE) or environment variables. Command-line arguments take precedence over environment variables, which in turn take precedence over the default values defined in the code.

   Example using command-line arguments (Recommended for MCP integration):

   Add the server configuration to your MCP client's settings (e.g., in VS Code settings.json):

   {
     "mcpServers": {
       "sd-image-gen": { // Choose a name for your server instance
         "command": "node",
         "args": [
           "/path/to/sd-image-gen-mcp/build/index.js"
         ],
         "env": {
           "SD_WEBUI_URL": "http://your-sd-webui-url:7860", // Required: URL of your Stable Diffusion WebUI instance
           "SD_OUTPUT_DIR": "/path/to/output/directory", // Optional: if not provided, images will be saved to the server's running directory
           "SD_AUTH_USER": "your-username",  // Optional: if authentication is enabled
           "SD_AUTH_PASS": "your-password",  // Optional: if authentication is enabled
           "SD_RESIZE_MODE": "0",           // Optional: upscaling mode (0=multiplier, 1=dimensions)
           "SD_UPSCALE_MULTIPLIER": "2",    // Optional: default upscale multiplier
           "SD_UPSCALE_WIDTH": "1024",       // Optional: default upscale width
           "SD_UPSCALE_HEIGHT": "1024",      // Optional: default upscale height
           "SD_UPSCALER_1": "R-ESRGAN 4x+", // Optional: default primary upscaler
           "SD_UPSCALER_2": "None",          // Optional: default secondary upscaler
           "CF_IMGBED_UPLOAD_URL": "https://your-imgbed-url/upload", // Optional: if Cloudflare ImgBed is enabled
           "CF_IMGBED_API_KEY": "your-imgbed-api-key", // Optional: if Cloudflare ImgBed is enabled
           "REQUEST_TIMEOUT": "300000"  // Optional: timeout for requests to the SD WebUI API
         }
       }
     }
   }

   Configuration Parameters:

   • SD_WEBUI_URL (Required): URL of your Stable Diffusion WebUI instance (e.g., http://127.0.0.1:7860).
   • SD_OUTPUT_DIR (Optional): Directory where generated images will be saved locally. Defaults to ./output relative to the server's running directory.
   • SD_AUTH_USER (Optional): Username for WebUI basic authentication, if enabled.
   • SD_AUTH_PASS (Optional): Password for WebUI basic authentication, if enabled.
   • REQUEST_TIMEOUT (Optional): Timeout in milliseconds for requests to the SD WebUI API. Defaults to 300000 (5 minutes).
   • CF_IMGBED_UPLOAD_URL (Optional): The upload endpoint URL for your Cloudflare ImgBed instance. If set along with CF_IMGBED_API_KEY, generated images will be uploaded.
   • CF_IMGBED_API_KEY (Optional): The API key (authCode) for your Cloudflare ImgBed instance.
   • SD_RESIZE_MODE (Optional): Default upscaling mode (0=multiplier, 1=dimensions). Defaults to 0.
   • SD_UPSCALE_MULTIPLIER (Optional): Default upscale multiplier when SD_RESIZE_MODE is 0. Defaults to 2.
   • SD_UPSCALE_WIDTH (Optional): Default target width when SD_RESIZE_MODE is 1. Defaults to 1024.
   • SD_UPSCALE_HEIGHT (Optional): Default target height when SD_RESIZE_MODE is 1. Defaults to 1024.
   • SD_UPSCALER_1 (Optional): Default primary upscaler model name. Defaults to "R-ESRGAN 4x+".
   • SD_UPSCALER_2 (Optional): Default secondary upscaler model name. Defaults to "None".

Features

Tools

• generate_image: Generate images using Stable Diffusion.

  • Parameters:
    • prompt (required): Text description of the desired image.
    • negative_prompt: Things to exclude from the image. (Defaults to a general list of negative terms if not provided).
    • steps: Number of sampling steps (default: 20, range: 1-150).
    • width: Image width (default: 1024, range: 512-2048).
    • height: Image height (default: 1024, range: 512-2048).
    • cfg_scale: CFG scale (default: 3.5, range: 1-30).
    • sampler_name: Sampling algorithm (default: "Euler a").
    • scheduler_name: Scheduler algorithm (default: "Automatic").
    • seed: Random seed (-1 for random).
    • batch_size: Number of images to generate (default: 1, max: 4).
    • restore_faces: Enable face restoration (boolean).
    • tiling: Generate tileable images (boolean).
    • output_path: Custom local output directory for the generated image(s), overrides SD_OUTPUT_DIR.
  • Returns: A JSON string representing an array of generated image results. Each result object contains:
    • path: The local file path where the image was saved.
    • parameters: The generation parameters string obtained from the image metadata.
    • url: The public URL of the image if uploaded to Cloudflare ImgBed (requires CF_IMGBED_UPLOAD_URL and CF_IMGBED_API_KEY to be configured), otherwise null.

• get_sd_models: Get list of available Stable Diffusion checkpoint models.

  • No parameters required.
  • Returns a JSON string array of model names (titles).

• set_sd_model: Set the active Stable Diffusion checkpoint model.

  • Parameters:
    • model_name (required): Name of the model to set as active.

• get_sd_upscalers: Get list of available upscaler models.

  • No parameters required.
  • Returns a JSON string array of upscaler names.

• upscale_images: Upscale one or more images using Stable Diffusion's "Extras" feature.

  • Parameters:
    • images (required): Array of local image file paths to upscale.
    • resize_mode: Upscaling mode (0 for multiplier, 1 for dimensions). Defaults to SD_RESIZE_MODE.
    • upscaling_resize: Upscale multiplier when resize_mode=0. Defaults to SD_UPSCALE_MULTIPLIER.
    • upscaling_resize_w: Target width in pixels when resize_mode=1. Defaults to SD_UPSCALE_WIDTH.
    • upscaling_resize_h: Target height in pixels when resize_mode=1. Defaults to SD_UPSCALE_HEIGHT.
    • upscaler_1: Primary upscaler model name. Defaults to SD_UPSCALER_1.
    • upscaler_2: Secondary upscaler model name. Defaults to SD_UPSCALER_2.
    • output_path: Custom local output directory for upscaled images, overrides SD_OUTPUT_DIR.
  • Returns: A JSON string representing an array of result objects, each containing the path to the upscaled image file.

Development

For development with auto-rebuild on file changes:

npm run watch

This will compile TypeScript files and restart the server when changes are detected in the src directory.

Error Handling

Common issues and solutions:

1. Connection Errors:
   • Ensure your Stable Diffusion WebUI is running and accessible from where the MCP server is running.
   • Verify the WebUI was started with the --api flag.
   • Check if the SD_WEBUI_URL is correct.
   • If using authentication (SD_AUTH_USER, SD_AUTH_PASS), ensure credentials are correct.
2. File System Errors:
   • Verify the output directory (SD_OUTPUT_DIR or output_path parameter) exists and the server process has write permissions.
   • When upscaling, ensure the input image files specified in the images array exist and are readable by the server process.
3. Timeout Errors:
   • Image generation can take time. If you encounter timeouts, consider increasing the REQUEST_TIMEOUT value (in milliseconds).
4. ImgBed Upload Errors:
   • Ensure CF_IMGBED_UPLOAD_URL and CF_IMGBED_API_KEY are correctly set if you expect uploads to work.
   • Check the ImgBed server logs for potential issues on its end.
   • Check the sd-image-gen-mcp server logs for detailed error messages related to the upload attempt.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.