A
licenseNot graded
qualityD
maintenanceGive AI agents full control over your local ComfyUI by exposing 77 tools for workflow management, image generation, model handling, and real-time canvas control.
4
AGPL 3.0
sd-api-mcp
by mcaimi
This MCP server exposes a Stable Diffusion REST API to AI agents for image generation, inpainting, model/job management, system inspection, and model merging.
Generate and inpaint images with SD1.5/SDXL/Illustrious/Flux pipelines, using prompts, checkpoints, dimensions, steps, CFG, seeds, schedulers, LoRAs, and custom VAEs.
Submit async generation/inpaint jobs, batch up to 10 requests, and compare 2–6 models using the same prompt.
List checkpoints, LoRAs, and VAEs, and read safetensors model metadata.
List jobs, check job status/results, and cancel pending or running jobs.
Check API health, get GPU/cache/queue stats, list schedulers, and read app settings.
Merge two checkpoints, batch-merge a base with multiple targets, or run multi-step merge recipes using linear, slerp, additive, or subtract methods.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sd-api-mcp Generate a photorealistic cat on a windowsill at golden hour using SDXL."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sd-api-mcp
An MCP (Model Context Protocol) server that exposes a Stable Diffusion REST API to AI agents. Supports SD1.5, SDXL, Illustrious XL, and Flux 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)
Related MCP server: invokeai-mcp
Installation
git clone <repo-url>
cd sd-api-mcp
uv syncUsage
stdio (default)
For use with MCP clients that manage the server process (e.g., Claude Code, Claude Desktop):
uv run sd-api-mcpSSE
uv run sd-api-mcp --transport sse --host 0.0.0.0 --port 8080Streamable HTTP (recommended for networked deployments)
uv run sd-api-mcp --transport streamable-http --host 0.0.0.0 --port 8080The 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-mcpOpenCode 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 |
|
| Base URL of the Stable Diffusion API |
|
| Seconds between job status polls |
|
| Maximum seconds to wait for job completion |
|
| Transport protocol ( |
|
| Bind address for SSE/HTTP transports |
|
| Port for SSE/HTTP transports |
Available Tools
Image Generation
Tool | Description |
| Generate an image and wait for the result |
| Inpaint a masked region and wait for the result |
| Submit a generation job, return the job ID immediately |
| Submit an inpainting job, return the job ID immediately |
| Submit up to 10 generation requests at once |
| Generate with 2-6 models using the same prompt for comparison |
All generation tools accept a pipeline parameter: "sd15", "sdxl", "illustrious", or "flux".
Flux differs from the SD/SDXL pipelines in a few ways:
It uses flow-matching schedulers (e.g.
"FlowMatch Euler"), not the SD/SDXL scheduler set returned bylist_schedulers.cfg_scaleis a distilled guidance scale with a default of3.5instead of7.0.generate_image/submit_generate/inpaint_image/submit_inpaintaccept a Flux-onlytrue_cfg_scaleparameter (1-10, default 1.0); set it above 1.0 to enablenegative_prompt.inpaint_image/submit_inpaintaccept a Flux-onlystrengthparameter (0-1) controlling re-noising strength.
Model Management
Tool | Description |
| List available checkpoints, LoRAs, or VAEs |
| Read metadata from a model's safetensors header |
Job Management
Tool | Description |
| List all jobs with status and progress |
| Get status and result of a specific job |
| Cancel a pending or running job |
System
Tool | Description |
| Check if the SD API is reachable |
| Get GPU, cache, and queue statistics |
| List available noise schedulers |
| Get current configuration parameters |
Model Merging
Tool | Description |
| Merge two checkpoints (linear, slerp, additive, subtract) |
| Merge a base model with multiple targets |
| 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 APILicense
This project is licensed under the GNU General Public License v3.0. See LICENSE for details.
Available Tools
18 toolsbatch_generateA
Submit a batch of image generation requests (up to 10).
Args:
pipeline: Pipeline to use — "sd15", "sdxl", or "illustrious"
requests: List of generation request objects, each with at least "positive_prompt" and "model_checkpoint"
Inputs: pipeline (required), requests (required). Returns: result
batch_merge_modelsA
Merge a base model with multiple target models in batch. Waits for completion.
Args:
model_type: Model architecture — "sd15" or "sdxl"
base_model: Base model checkpoint filename
target_models: List of target model checkpoint filenames
method: Merge method — "linear", "slerp", "additive", or "subtract"
alpha: Merge strength (0.0-1.0)
output_subdir: Output subdirectory name for merged models
preserve_metadata: Whether to preserve model metadata
Inputs: base_model (required), model_type (required), target_models (required), alpha, +3 more. Returns: result
cancel_jobA
Cancel a pending or running job.
Args:
job_id: The job identifier to cancel
Inputs: job_id (required). Returns: result
compare_modelsA
Generate images from multiple models using the same prompt for comparison.
Args:
pipeline: Pipeline to use — "sd15", "sdxl", or "illustrious"
positive_prompt: Text prompt for all models
models: List of model checkpoint filenames to compare (2-6)
negative_prompt: Negative prompt (things to avoid)
width: Image width in pixels (256-2048)
height: Image height in pixels (256-2048)
steps: Number of inference steps (1-150)
cfg_scale: Classifier-free guidance scale (1-30)
seed: Fixed seed for fair comparison (default 42)
scheduler: Noise scheduler name
Inputs: models (required), pipeline (required), positive_prompt (required), seed, +6 more. Returns: result
generate_imageA
Generate an image using Stable Diffusion. Waits for completion and returns the result.
Args:
pipeline: Pipeline to use — "sd15", "sdxl", or "illustrious"
positive_prompt: Text prompt describing the desired image
model_checkpoint: Model checkpoint filename to use
negative_prompt: Negative prompt (things to avoid)
width: Image width in pixels (256-2048)
height: Image height in pixels (256-2048)
steps: Number of inference steps (1-150)
cfg_scale: Classifier-free guidance scale (1-30)
seed: Random seed (-1 for random)
scheduler: Noise scheduler name
loras: Optional list of LoRA configs, each with "name" (str) and optional "strength" (float 0-1)
custom_vae: Optional custom VAE checkpoint filename
Inputs: pipeline (required), positive_prompt (required), model_checkpoint (required), seed, +8 more. Returns: result
get_app_settingsA
Get the current application configuration parameters.
Inputs: no named parameters. Returns: result
get_job_statusB
Get the current status and result of a specific job.
Args:
job_id: The job identifier returned when the job was submitted
Inputs: job_id (required). Returns: result
get_model_metadataA
Get metadata for a specific model from its safetensors header.
Args:
model_type: Model architecture — "sd15" or "sdxl"
resource_type: Resource category — "checkpoints", "loras", or "vaes"
model_name: Model filename
Inputs: model_name (required), model_type (required), resource_type (required). Returns: result
health_checkA
Check if the Stable Diffusion API is healthy and reachable.
Inputs: no named parameters. Returns: result
inpaint_imageA
Inpaint an image using Stable Diffusion. Waits for completion and returns the result.
Args:
pipeline: Pipeline to use — "sd15", "sdxl", or "illustrious"
positive_prompt: Text prompt describing what to paint in the masked region
model_checkpoint: Model checkpoint filename to use
image_base64: Base64-encoded input image
mask_base64: Base64-encoded mask image (white = inpaint region)
negative_prompt: Negative prompt (things to avoid)
steps: Number of inference steps (1-150)
cfg_scale: Classifier-free guidance scale (1-30)
seed: Random seed (-1 for random)
scheduler: Noise scheduler name
loras: Optional list of LoRA configs, each with "name" (str) and optional "strength" (float 0-1)
custom_vae: Optional custom VAE checkpoint filename
Inputs: pipeline (required), mask_base64 (required), image_base64 (required), positive_prompt (required), +8 more. Returns: result
list_jobsA
List all jobs with their current status, progress, and timing information.
Inputs: no named parameters. Returns: result
list_modelsB
List available models.
Args:
model_type: Model architecture — "sd15" or "sdxl"
resource_type: Resource category — "checkpoints", "loras", or "vaes"
Inputs: model_type (required), resource_type (required). Returns: result
list_schedulersA
List all available noise schedulers that can be used for image generation.
Inputs: no named parameters. Returns: result
merge_modelsA
Merge two model checkpoints. Submits the job and waits for completion.
Args:
model_type: Model architecture — "sd15" or "sdxl"
base_model: Base model checkpoint filename
target_model: Target model checkpoint filename
output_name: Output checkpoint filename for the merged model
method: Merge method — "linear", "slerp", "additive", or "subtract"
alpha: Merge strength (0.0-1.0)
preserve_metadata: Whether to preserve model metadata
Inputs: base_model (required), model_type (required), output_name (required), target_model (required), +3 more. Returns: result
recipe_mergeB
Execute a multi-step merge recipe. Each step merges the current result with a new target. Waits for completion.
Args:
model_type: Model architecture — "sd15" or "sdxl"
base_model: Base model checkpoint filename
steps: List of merge steps, each with "target_model" (str), "method" (str), and "alpha" (float 0-1)
output_name: Output checkpoint filename for the final merged model
Inputs: steps (required), base_model (required), model_type (required), output_name (required). Returns: result
submit_generateA
Submit an image generation job without waiting. Returns the job ID for manual polling.
Args:
pipeline: Pipeline to use — "sd15", "sdxl", or "illustrious"
positive_prompt: Text prompt describing the desired image
model_checkpoint: Model checkpoint filename to use
negative_prompt: Negative prompt (things to avoid)
width: Image width in pixels (256-2048)
height: Image height in pixels (256-2048)
steps: Number of inference steps (1-150)
cfg_scale: Classifier-free guidance scale (1-30)
seed: Random seed (-1 for random)
scheduler: Noise scheduler name
loras: Optional list of LoRA configs, each with "name" (str) and optional "strength" (float 0-1)
custom_vae: Optional custom VAE checkpoint filename
Inputs: pipeline (required), positive_prompt (required), model_checkpoint (required), seed, +8 more. Returns: result
submit_inpaintA
Submit an inpainting job without waiting. Returns the job ID for manual polling.
Args:
pipeline: Pipeline to use — "sd15", "sdxl", or "illustrious"
positive_prompt: Text prompt describing what to paint in the masked region
model_checkpoint: Model checkpoint filename to use
image_base64: Base64-encoded input image
mask_base64: Base64-encoded mask image (white = inpaint region)
negative_prompt: Negative prompt (things to avoid)
steps: Number of inference steps (1-150)
cfg_scale: Classifier-free guidance scale (1-30)
seed: Random seed (-1 for random)
scheduler: Noise scheduler name
loras: Optional list of LoRA configs, each with "name" (str) and optional "strength" (float 0-1)
custom_vae: Optional custom VAE checkpoint filename
Inputs: pipeline (required), mask_base64 (required), image_base64 (required), positive_prompt (required), +8 more. Returns: result
system_infoA
Get system information including GPU device, dtype, model cache stats, and job queue stats.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.7/5.0
Scored across 18 tools
Disambiguation4/5
Most tools target distinct operations (sync generation, async submission, batch, compare, merge variants), and descriptions clarify the differences. A few near pairs such as generate_image/submit_generate and batch_merge_models/recipe_merge could cause misselection, but the descriptions separate them well.
Naming Consistency3/5
The dominant verb_noun pattern (list_models, get_job_status, merge_models) is readable, but there are notable deviations like health_check, system_info, recipe_merge, and submit_generate. The mix of verb-first and noun-first names is inconsistent enough to slow an agent down.
Tool Count4/5
Eighteen tools is slightly above the ideal 3-15 range, but the breadth is justified by covering generation, async jobs, model metadata, system health, and model merging. It feels like a complete API surface rather than an inflated one.
Completeness4/5
The surface covers generation, inpainting, async job lifecycle, model listing/metadata, schedulers, and multiple merge workflows. Obvious gaps are minor, such as the lack of a general image-to-image tool or batch async variants, but core workflows have no dead ends.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues
Related MCP Connectors
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
Image and video AI tools and your own pipelines, run from any AI assistant.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Generate images, videos and music with model discovery, cost estimates and asynchronous results.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI coding agents to control a local InvokeAI creative engine, supporting text-to-image, image-to-image, masked inpaint, upscaling, and full queue, model, gallery, board, and workflow management.132MIT
- AlicenseCqualityCmaintenanceEnables LLM hosts to control SD.Next (Stable Diffusion Next) WebUI via 125 MCP tools for text-to-image, image-to-image, upscaling, control, tagging, model management, and more.125MIT
- AlicenseAqualityBmaintenanceEnables AI agents to generate images on a local Stable Diffusion Forge Neo instance, automatically inferring prompt style and sampling parameters from the user's setup and past generations, and providing tools for LoRA search, model management, and module checks.101MIT