sd-webui-mcp

SD WebUI MCP Server

An MCP (Model Context Protocol) server that connects Claude Desktop to your local Stable Diffusion WebUI installation, enabling AI-assisted image generation directly from your conversations.

🔋 Overview

This project allows you to utilize your local Stable Diffusion installation through Claude Desktop, giving you the ability to:

• Generate images from text descriptions
• Edit existing images with text prompts
• List and switch between different Stable Diffusion models
• Access advanced image generation parameters
• View image thumbnails directly in Claude responses

All while staying within the Claude Desktop interface, without switching between applications.

🎯 Features

• Text-to-Image Generation: Create images from text prompts
• Image-to-Image Editing: Modify existing images using text guidance
• Model Management: List and switch between your installed models
• Sampler Control: Access all WebUI samplers
• Connection Status: Verify connectivity with your local Stable Diffusion
• High Performance: Uses your local GPU resources for image generation
• Privacy-Focused: All processing happens on your machine
• Base64 Thumbnails: See images directly in Claude responses
• SDXL Optimized: Default settings tuned for SDXL's 1024x1024 resolution

📦 Prerequisites

• Node.js v16.0.0 or higher
• Stable Diffusion WebUI with API enabled
• Claude Desktop
• Basic familiarity with command line interfaces

🚀 Installation

1. Clone this repository

git clone https://github.com/boxi-rgb/sd-webui-mcp.git
cd sd-webui-mcp

2. Install dependencies

npm install

3. Build the project

npm run build

4. Configure Stable Diffusion WebUI

Make sure your Stable Diffusion WebUI is running with the API enabled.

For Windows:

Edit your webui-user.bat file and add --api to the COMMANDLINE_ARGS:

@echo off
set COMMANDLINE_ARGS=--api
call webui.bat

For Linux/macOS:

Edit your webui-user.sh file and add --api to the COMMANDLINE_ARGS:

export COMMANDLINE_ARGS="--api"
./webui.sh

5. Configure Claude Desktop

1. Open Claude Desktop
2. Go to Settings
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Add the following to the claude_desktop_config.json file (create it if it doesn't exist):

{
  "mcpServers": {
    "stable-diffusion": {
      "command": "node",
      "args": [
        "/FULL/PATH/TO/sd-webui-mcp/dist/index.js"
      ]
    }
  }
}

Important: Replace /FULL/PATH/TO/ with the actual full path to your project directory. For Windows users, use double backslashes (\\) or forward slashes (/) in your path.

4. Save the file and restart Claude Desktop

⚙️ Usage

Step 1: Verify installation

After starting Claude Desktop, you should see a tools icon (🔧) in the bottom right corner of the chat interface. Click on it to see if "stable-diffusion" appears in the list of available tools.

Step 2: Check connection

Type the following message to Claude:

Can you check if Stable Diffusion is connected properly?

Claude should use the check-status tool to verify the connection with your local Stable Diffusion WebUI.

Step 3: Generate your first image

Type something like:

Please create an image of a futuristic city with flying cars.

Claude will use the generate-image tool to send your request to Stable Diffusion and display the resulting image.

Advanced Usage

The MCP server provides several tools that Claude can use:

1. Image Generation

Generate an image of a cat wearing a space suit on Mars.

You can add more detailed parameters:

Generate an image of a mountain landscape with the following parameters:
- Width: 1024
- Height: 1024
- Steps: 30
- CFG Scale: 8
- Negative prompt: blurry, low quality

2. Model Switching

First, check available models:

What Stable Diffusion models are available on my system?

Then switch models:

Please switch to the AnythingV5 model.

3. Editing Existing Images

Save an image to your system, then:

Edit the image at C:/path/to/image.png to add flowers in the background.

4. List Sampling Methods

What samplers are available in my Stable Diffusion setup?

🔧 Configuration

You can customize the behavior of the MCP server by modifying src/config.ts:

• SD_API_URL: The URL of your Stable Diffusion WebUI API (default: http://127.0.0.1:7860)
• OUTPUT_DIR: Directory where generated images will be saved (default: C:\SD_Output)
• DEFAULT_PARAMS: Default image generation parameters optimized for SDXL (1024x1024 resolution)

After modifying, rebuild the project with npm run build.

🔍 Troubleshooting

Common Issues

MCP server not found in Claude Desktop

• Verify the path in claude_desktop_config.json is correct
• Ensure you've included the full absolute path to the dist/index.js file
• Check if the Node.js path is correct

Cannot connect to Stable Diffusion WebUI

• Make sure Stable Diffusion WebUI is running
• Verify that it was started with the --api flag
• Check if the default port (7860) is being used or if you need to specify a custom port in config.ts

Images not being generated

• Check the output directory exists and has write permissions
• Look for error messages in the Claude Desktop console
• Try running the check-status tool to verify connectivity

Debugging

If you're experiencing issues, you can enable more verbose logging by:

1. Running the MCP server directly from the command line to see error messages:

node dist/index.js

2. You can also use the MCP Inspector for debugging:

npx @modelcontextprotocol/inspector node /path/to/sd-webui-mcp/dist/index.js

📝 License

MIT License

⚠️ Disclaimer

This project is not officially affiliated with Anthropic (creators of Claude) or Stable Diffusion. Use at your own risk.