# comfyui-mcp
## 基本信息
- Slug: `purlieustudios-comfyui-mcp`
- Source: modelscope
- Publisher: @PurlieuStudios/comfyui-mcp
- Categories: image-and-video-processing / games-and-gamification / developer-tools
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@PurlieuStudios/comfyui-mcp
## 简介
暂无描述。
## 安装提示

```bash
python --version # Should be 3.10+ ``` 2. **ComfyUI installed and running** - Download: [ComfyUI GitHub](https://github.com/comfyanonymous/ComfyUI) - Default URL: `http://localhost:8188` - Verify: Open `http://localhost:8188` in your browser 3. **Stable Diffusion models** - Download models and place in ComfyUI's `models/checkpoints/` directory - Recommended: Stable Diffusion 1.5 or 2.1 for game assets ### Installation ```bash # Clone the repository git clone https://github.com/purlieu-studios/comfyui-mcp.git cd comfyui-mcp # Install the package pip install -e . # For development (includes testing and linting tools) pip install -e ".[dev]" # Verify installation python -c "from comfyui_mcp import ComfyUIClient; print('Installation successful!')"
```

## MCP Server 详情

# ComfyUI MCP Server

> AI-powered image generation for game development via ComfyUI and the Model Context Protocol

[![CI](https://github.com/purlieu-studios/comfyui-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/purlieu-studios/comfyui-mcp/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)

## Overview

ComfyUI MCP Server is a **Model Context Protocol (MCP) server** that bridges [ComfyUI](https://github.com/comfyanonymous/ComfyUI)'s powerful workflow-based AI image generation with modern development workflows. Originally designed for [Godot](https://godotengine.org/) game development, it can be used with any MCP-compatible client to generate game assets, concept art, and visual content dynamically.

### Key Features

- **MCP Integration**: Expose ComfyUI workflows as standardized MCP tools
- **Python API Client**: Full-featured async ComfyUI API client with type safety
- **Workflow Templates**: Pre-built templates for common game assets (characters, items, environments)
- **Async Operations**: Non-blocking generation with real-time progress updates via WebSockets
- **Flexible Configuration**: TOML files, environment variables, or Python code
- **Type Safe**: Full type hints with strict mypy validation
- **Well Tested**: Comprehensive test coverage with pytest
- **Production Ready**: Retry logic, error handling, and logging built-in

### Use Cases

- **Character Generation**: NPC portraits, character sprites, concept art
- **Item Icons**: Unique item icons from text descriptions
- **Environment Art**: Background textures, tileable patterns, landscapes
- **Dynamic Content**: Procedural asset generation during gameplay
- **Concept Art**: Rapid visual prototyping and iteration
- **Batch Processing**: Generate multiple asset variations efficiently

---

## Table of Contents

- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [MCP Server](#mcp-server-usage)
  - [Python API Client](#python-api-client)
- [Workflow Templates](#workflow-templates)
- [Documentation](#documentation)
- [Examples](#examples)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

---

## Quick Start

### Prerequisites

1. **Python 3.10 or higher**
   ```bash
   python --version  # Should be 3.10+
   ```

2. **ComfyUI installed and running**
   - Download: [ComfyUI GitHub](https://github.com/comfyanonymous/ComfyUI)
   - Default URL: `http://localhost:8188`
   - Verify: Open `http://localhost:8188` in your browser

3. **Stable Diffusion models**
   - Download models and place in ComfyUI's `models/checkpoints/` directory
   - Recommended: Stable Diffusion 1.5 or 2.1 for game assets

### Installation

```bash
# Clone the repository
git clone https://github.com/purlieu-studios/comfyui-mcp.git
cd comfyui-mcp

# Install the package
pip install -e .

# For development (includes testing and linting tools)
pip install -e ".[dev]"

# Verify installation
python -c "from comfyui_mcp import ComfyUIClient; print('Installation successful!')"
```

### Basic Configuration

**Option 1: Environment Variables (Recommended for getting started)**

```bash
# Required
export COMFYUI_URL="http://localhost:8188"

# Optional
export COMFYUI_TIMEOUT="120.0"
export COMFYUI_OUTPUT_DIR="./generated_images"
```

**Option 2: TOML Configuration File**

Create `comfyui.toml` in your project root:

```toml
[comfyui]
url = "http://localhost:8188"
timeout = 120.0
output_dir = "./generated_images"
```

See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for comprehensive configuration options.

### Your First Generation

#### Using the Python API

```python
import asyncio
from comfyui_mcp import ComfyUIClient, ComfyUIConfig, WorkflowPrompt

async def generate_image():
    # Configure the client
    config = ComfyUIConfig(url="http://localhost:8188")

    async with ComfyUIClient(config) as client:
        # Check ComfyUI server health
        if not await client.health_check():
            print("ComfyUI server is not responding!")
            return

        # Create a simple workflow
        workflow = WorkflowPrompt(
            prompt={
                "3": {
                    "class_type": "KSampler",
                    "inputs": {
                        "seed": 42,
                        "steps": 20,
                        "cfg": 7.0,
                        "sampler_name": "euler",
                        "scheduler": "normal",
                        "denoise": 1.0
                    }
                }
            }
        )

        # Submit and wait for completion
        prompt_id = await client.submit_workflow(workflow)
        print(f"Workflow submitted: {prompt_id}")

        result = await client.wait_for_completion(
            prompt_id=prompt_id,
            poll_interval=1.0,
            timeout=300.0
        )

        print(f"Generation complete! Result: {result}")

# Run the async function
asyncio.run(generate_image())
```

#### Using the MCP Server

**1. Configure MCP Server**

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "comfyui-mcp": {
      "command": "python",
      "args": ["-m", "comfyui_mcp.server"],
      "env": {
        "COMFYUI_URL": "http://localhost:8188",
        "COMFYUI_OUTPUT_DIR": "./generated_images"
      }
    }
  }
}
```

**More Configuration Examples:**

Complete `.mcp.json` configuration examples are available in [`examples/mcp/`](examples/mcp/):

| Example | Description | Use Case |
|---------|-------------|----------|
| [`basic.mcp.json`](…