ComfyMCP Studio

ComfyMCP Studio is an MCP (Model Context Protocol) server for generating 2D game assets using AI workflows powered by ComfyUI.

What you get

ComfyUI-backed generation
- Production-quality SDXL/SD1.5 workflows
High-quality outputs by default
- Render at preset resolution (SDXL-native) then downscale for cleaner details
Consistent character animations (img2img)
- Generate multiple poses from a single reference image
Viewpoint control with ControlNet (top-down / side / front / 3/4)
- Generate top-down assets with stronger camera-angle consistency
Presets for common game styles
- Icon, character, tileset, top-down presets, pixel presets
Post-processing
- Resize, remove background, add outline
Unity export + batch generation

Requirements

Python: 3.10+
ComfyUI: running locally (default 127.0.0.1:8188)
Stable Diffusion checkpoint
- SDXL recommended (default configured: sd_xl_base_1.0.safetensors)
(Optional) ControlNet models
- Required only for generate_with_viewpoint / generate_topdown_asset

Installation

# Navigate to the project
cd path/ComfyAI-MCP-GameAssets

# Create virtual environment
python -m venv venv
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration

Copy .env.example to .env and configure:

BACKEND_TYPE=comfyui
COMFYUI_HOST=127.0.0.1
COMFYUI_PORT=8188
COMFYUI_CHECKPOINT=sd_xl_base_1.0.safetensors

OUTPUT_DIR=./output
UNITY_ASSETS_DIR=C:/Projects/MyGame/Assets

ComfyUI setup

Start ComfyUI (example):

python main.py --listen 0.0.0.0 --port 8188

Checkpoint
- Make sure your checkpoint exists in ComfyUI (example: ComfyUI/models/checkpoints/).
- This server reads COMFYUI_CHECKPOINT from .env.

ControlNet setup (for viewpoint locking)

If you use viewpoint tools, you must install a ControlNet model in: ComfyUI/models/controlnet/

SDXL depth model (example)
- diffusers_xl_depth_full.safetensors

Restart ComfyUI after adding models.

If you see HTTP 400 Bad Request when calling /prompt, it usually means:

The controlnet_model name is wrong, or
The ControlNet nodes/models are not installed/available.

Run as MCP server (Windsurf)

Add this to your MCP settings (or copy from mcp_config.json):

{
  "mcpServers": {
    "comfymcp-studio": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "path/ComfyAI-MCP-GameAssets",
      "env": {
        "BACKEND_TYPE": "comfyui",
        "COMFYUI_HOST": "127.0.0.1",
        "COMFYUI_PORT": "8188"
      }
    }
  }
}

Tools

ping - Backend health check
list_available_presets - Lists preset names + configs
generate_sprite - Single image generation from prompt
generate_icons - Batch icons + optional atlas
generate_tileset - Tileable tiles by theme
generate_character - Character generation (prompt-driven)
generate_character_animations - Img2img multi-pose animations from a reference image
generate_with_viewpoint - ControlNet depth-guided generation for stable camera angle
generate_topdown_asset - Convenience wrapper for top-down assets (prop, character, creature, tile, effect)
process_image - Resize / remove background / add outline
create_sprite_atlas - Combine images to spritesheet
export_to_unity - Export output PNGs into a Unity project folder
batch_generate - Batch generation with prompts

Presets

You can list presets via list_available_presets.

General

default - General purpose game asset
icon / icon_item - Game icons
character / character_portrait - Character sprites
tileset - Seamless tileable textures
environment - Background/environment art
prop - Game props (3/4 view)

Top-down (ControlNet)

topdown_prop - Top-down props
topdown_character - Top-down characters
topdown_creature - Top-down creatures/enemies
topdown_tile - Top-down tiles

Effects & UI

effect / magic_effect - VFX and spell effects
ui_button / ui_frame - UI elements

Creatures

creature - Fantasy creatures/monsters

Style-specific

handpainted - Hand-painted art style
flat_ui - Flat design UI
isometric - Isometric game assets
pixel_art / pixel_character - Pixel art style
pixel_16 / pixel_32 / pixel_64 - Specific pixel sizes

Testing

Quick smoke test

python test_generate.py --list-presets
python test_generate.py --preset icon --size 256 --steps 20 --seed 42 --save

ControlNet viewpoint tests

# Top-down prop (depth ControlNet)
python test_controlnet.py --tests prop --size 512 --strength 0.95 --save

# Top-down character (wrapper tool)
python test_controlnet.py --tests character --size 512 --strength 1.0 --save

# Multi-view for the same object
python test_controlnet.py --tests multi --views topdown,side,front,3/4 --size 512 --strength 0.90 --save

Character animation tests (img2img)

# Requires a local reference image
python test_character_animation.py --ref path\\to\\reference.png --poses idle,walking,attacking --denoise 0.35 --seed 42 --save

Output

Generated images are saved under OUTPUT_DIR when you call tools with save_to_file=true. Typical folders:

output/controlnet/
output/icons/
output/characters/
output/tilesets/

Troubleshooting

HTTP 400 Bad Request from ComfyUI /prompt
- Check ControlNet model file exists in ComfyUI/models/controlnet/
- Verify the exact filename passed as controlnet_model
- Restart ComfyUI after installing models
Results still not top-down
- Increase control_strength (try 0.90 to 1.0)
- Use preset=topdown_character/topdown_prop
Duplicated/fragmented weapons/armor
- Add explicit constraints to prompt: single character, one sword, one shield

License

MIT