sd-api-mcp

An MCP (Model Context Protocol) server that exposes a Stable Diffusion REST API to AI agents. Supports SD1.5, SDXL, and Illustrious XL pipelines for text-to-image generation, inpainting, model management, and model merging.

It sits on top of the SD API Backend project.

Built with the MCP Python SDK and managed with uv.

Requirements

• Python >= 3.11
• uv package manager
• A running Stable Diffusion API instance (default: http://localhost:8000)

Installation

git clone <repo-url>
cd sd-api-mcp
uv sync

Usage

stdio (default)

For use with MCP clients that manage the server process (e.g., Claude Code, Claude Desktop):

uv run sd-api-mcp

SSE

uv run sd-api-mcp --transport sse --host 0.0.0.0 --port 8080

Streamable HTTP (recommended for networked deployments)

uv run sd-api-mcp --transport streamable-http --host 0.0.0.0 --port 8080

The MCP endpoint will be available at http://<host>:<port>/mcp.

Claude Desktop configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "stable-diffusion": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/sd-api-mcp", "sd-api-mcp"],
      "env": {
        "SD_API_URL": "http://localhost:8000"
      }
    }
  }
}

Claude Code configuration

claude mcp add stable-diffusion -- uv run --project /path/to/sd-api-mcp sd-api-mcp

OpenCode configuration

Add to your opencode.json:

{
  "mcp": {
    "stable-diffusion": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--project", "/path/to/sd-api-mcp", "sd-api-mcp"],
      "env": {
        "SD_API_URL": "http://localhost:8000"
      }
    }
  }
}

For SSE or Streamable HTTP transports, start the server separately and use a remote URL instead:

{
  "mcp": {
    "stable-diffusion": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Environment Variables

Variable	Default	Description
SD_API_URL	http://localhost:8000	Base URL of the Stable Diffusion API
SD_POLL_INTERVAL	2.0	Seconds between job status polls
SD_POLL_TIMEOUT	600.0	Maximum seconds to wait for job completion
MCP_TRANSPORT	stdio	Transport protocol (stdio, sse, streamable-http)
MCP_HOST	127.0.0.1	Bind address for SSE/HTTP transports
MCP_PORT	8080	Port for SSE/HTTP transports

Available Tools

Image Generation

Tool	Description
generate_image	Generate an image and wait for the result
inpaint_image	Inpaint a masked region and wait for the result
submit_generate	Submit a generation job, return the job ID immediately
submit_inpaint	Submit an inpainting job, return the job ID immediately
batch_generate	Submit up to 10 generation requests at once
compare_models	Generate with 2-6 models using the same prompt for comparison

All generation tools accept a pipeline parameter: "sd15", "sdxl", or "illustrious".

Model Management

Tool	Description
list_models	List available checkpoints, LoRAs, or VAEs
get_model_metadata	Read metadata from a model's safetensors header

Job Management

Tool	Description
list_jobs	List all jobs with status and progress
get_job_status	Get status and result of a specific job
cancel_job	Cancel a pending or running job

System

Tool	Description
health_check	Check if the SD API is reachable
system_info	Get GPU, cache, and queue statistics
list_schedulers	List available noise schedulers
get_app_settings	Get current configuration parameters

Model Merging

Tool	Description
merge_models	Merge two checkpoints (linear, slerp, additive, subtract)
batch_merge_models	Merge a base model with multiple targets
recipe_merge	Execute a multi-step merge recipe

Examples

Generate an image (agent perspective)

An AI agent would call the generate_image tool with:

{
  "pipeline": "sdxl",
  "positive_prompt": "a cat sitting on a windowsill, golden hour lighting, photorealistic",
  "negative_prompt": "blurry, low quality",
  "model_checkpoint": "dreamshaperXL_v2.safetensors",
  "width": 1024,
  "height": 1024,
  "steps": 30,
  "cfg_scale": 7.0,
  "seed": -1,
  "scheduler": "DPM++ 2M"
}

The tool submits the job to the SD API, polls until completion, and returns the full result including the generated image.

List available models

{
  "model_type": "sdxl",
  "resource_type": "checkpoints"
}

Merge two models

{
  "model_type": "sd15",
  "base_model": "v1-5-pruned.safetensors",
  "target_model": "dreamshaper_8.safetensors",
  "output_name": "merged_model.safetensors",
  "method": "slerp",
  "alpha": 0.5
}

Project Structure

src/sd_api_mcp/
    __init__.py   # CLI entry point with transport selection
    server.py     # MCPServer instance and tool definitions
    client.py     # Async HTTP client for the SD API

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.