SwarmUI MCP Server

A Model Context Protocol (MCP) server that provides tools for generating images using SwarmUI's HTTP API. This server enables you to generate images with customizable parameters directly through MCP-compatible clients.

Features

• Image Generation: Generate images with full control over parameters like prompt, model, dimensions, steps, CFG scale, seed, and more
• Model Management: List available models and their categories
• Status Monitoring: Check generation queue status and backend health
• Parameter Discovery: Explore all available generation parameters dynamically
• Session Management: Automatic session handling with renewal
• Error Handling: Comprehensive error handling with retry logic

Available Tools

generate_image

Generate images using SwarmUI with customizable parameters.

Parameters:

• prompt (required): Text description of the image to generate
• negative_prompt (optional): Text description of what to avoid in the image
• model (optional): Model to use (e.g., 'OfficialStableDiffusion/sd_xl_base_1.0')
• width (optional): Image width in pixels (64-2048, default: 1024)
• height (optional): Image height in pixels (64-2048, default: 1024)
• steps (optional): Number of inference steps (1-150, default: 20)
• cfg_scale (optional): Classifier-free guidance scale (1-30, default: 7.5)
• seed (optional): Random seed for reproducible results (-1 for random, default: -1)
• sampler (optional): Sampling method to use
• batch_size (optional): Number of images to generate (1-10, default: 1)
• do_not_save (optional): If true, don't save images to disk (default: false)

list_models

Get a list of available models in SwarmUI organized by category.

get_generation_status

Get the current status of the SwarmUI generation queue and backend health.

list_parameters

Get a comprehensive list of all available generation parameters and their details.

Prerequisites

1. SwarmUI Installation: You need a running SwarmUI instance

   • Download from: https://github.com/mcmonkeyprojects/SwarmUI
   • Follow the installation instructions for your platform
   • Ensure SwarmUI is running on the configured URL (default: http://localhost:7801)

2. Node.js: Required for running the MCP server

   • Version 16 or higher recommended

Installation

The server has been automatically installed and configured in your MCP settings. It's located at:

/home/coder/Cline/MCP/swarmui-server/

Configuration

The server is configured in your MCP settings file with the following default configuration:

{
  "mcpServers": {
    "swarmui": {
      "command": "npx",
      "args": ["-y", "swarmui-server"],
      "env": {
        "SWARMUI_URL": "http://localhost:7801"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Environment Variables

• SWARMUI_URL: The URL where SwarmUI is running (default: http://localhost:7801)
• SWARMUI_TOKEN: Optional authentication token if SwarmUI requires accounts

Customizing the Configuration

To modify the configuration:

1. Change SwarmUI URL: Update the SWARMUI_URL environment variable if your SwarmUI instance runs on a different port or host
2. Add Authentication: If your SwarmUI instance requires authentication, add the SWARMUI_TOKEN environment variable
3. Enable Auto-Approve: Add tool names to the autoApprove array to automatically approve certain operations

Example with custom configuration:

{
  "mcpServers": {
    "swarmui": {
      "command": "npx",
      "args": ["-y", "swarmui-server"],
      "env": {
        "SWARMUI_URL": "http://192.168.1.100:7801",
        "SWARMUI_TOKEN": "your-auth-token-here"
      },
      "disabled": false,
      "autoApprove": ["list_models", "get_generation_status"]
    }
  }
}

Usage Examples

Once SwarmUI is running and the MCP server is configured, you can use the tools through your MCP client:

Basic Image Generation

Generate an image of "a beautiful sunset over mountains"

Advanced Image Generation

Generate an image with these parameters:
- Prompt: "a cyberpunk cityscape at night, neon lights, rain"
- Negative prompt: "blurry, low quality"
- Model: "OfficialStableDiffusion/sd_xl_base_1.0"
- Size: 1024x768
- Steps: 30
- CFG Scale: 8.0
- Seed: 12345

Check Available Models

List all available models in SwarmUI

Monitor Generation Status

Check the current generation queue status

Setting Up SwarmUI

If you don't have SwarmUI installed yet:

1. Download SwarmUI:

   git clone https://github.com/mcmonkeyprojects/SwarmUI.git
   cd SwarmUI

2. Install Dependencies (varies by platform):

   • Windows: Run launch-windows.bat
   • Linux: Run launch-linux.sh
   • macOS: Run launch-macos.sh

3. First Run: SwarmUI will download required models on first startup

4. Access Web Interface: Open http://localhost:7801 in your browser to verify it's working

5. Test the MCP Server: Once SwarmUI is running, the MCP tools should work without connection errors

Troubleshooting

Connection Refused Error

If you get a "connection refused" error:

• Ensure SwarmUI is running on the configured URL
• Check that the port (default 7801) is not blocked by firewall
• Verify the SWARMUI_URL environment variable is correct

Authentication Errors

If you get authentication errors:

• Check if your SwarmUI instance requires accounts
• Add the SWARMUI_TOKEN environment variable with a valid token
• Obtain the token from SwarmUI's web interface

Model Not Found Errors

If you get model-related errors:

• Use the list_models tool to see available models
• Ensure the model name exactly matches what's available
• Wait for SwarmUI to finish downloading models if it's still starting up

Session Expired Errors

The server automatically handles session renewal, but if you encounter persistent session issues:

• Restart the MCP server
• Check SwarmUI logs for any backend issues

Development

To modify or extend the server:

1. Edit Source: Modify /home/coder/Cline/MCP/swarmui-server/src/index.ts
2. Rebuild: Run npm run build in the server directory
3. Restart: The MCP system will automatically restart the server

Adding New Tools

To add new tools, extend the setupToolHandlers() method in the SwarmUIServer class and add corresponding handler methods.

API Reference

The server implements the SwarmUI HTTP API endpoints:

• /API/GetNewSession - Session management
• /API/GenerateText2Image - Image generation
• /API/ListT2IParams - Parameter and model listing
• /API/GetCurrentStatus - Status monitoring

For detailed API documentation, see:

• SwarmUI API Documentation
• T2I API Routes

License

This MCP server is provided as-is for use with SwarmUI. Please refer to SwarmUI's license for usage terms.