# comfyui-mcp **Repository Path**: alan-ding/comfyui-mcp ## Basic Information - **Project Name**: comfyui-mcp - **Description**: 基于 FastMCP 的 ComfyUI MCP服务器,提供图像生成和音乐生成功能 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-09-05 - **Last Updated**: 2026-11-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ComfyUI MCP Server 基于 [FastMCP](https://github.com/jlowin/fastmcp) 的 ComfyUI MCP服务器,提供图像生成和音乐生成功能。 ## 工作流程说明 ```mermaid graph TB A[用户请求] --> B[OpenCode Agent] B --> C{选择 Skill} C --> D[text-to-image] C --> E[text-to-music] D --> F[参数优化] E --> F F --> G[MCP 工具调用] G --> H[comfyui-mcp server] H --> I[ComfyUI API] I --> J[执行工作流] J --> K[结果返回] K --> L[下载到 output/] ``` ## 系统要求 - Python 3.11+ - ComfyUI 服务运行在 `http://127.0.0.1:8188`(可配置) - 工作流文件(已包含在 `workflow-api/` 目录) ## 安装步骤 1. **克隆项目** ```bash git clone https://gitee.com/alan-ding/comfyui-mcp.git cd comfyui-mcp ``` 2. **创建虚拟环境** ```bash uv venv .venv\Scripts\activate # Windows # source .venv/bin/activate # Linux/macOS ``` 3. **安装依赖** ```bash uv sync ``` ## 配置说明 项目使用环境变量进行配置,主要配置项如下: | 变量名 | 说明 | 默认值 | |--------|------|--------| | `SERVER_ADDRESS` | ComfyUI 服务器地址 | `http://127.0.0.1:8188` | | `WORKFLOW_QWEN_IMAGE_PATH` | 图像生成工作流文件名 | `image_qwen_image_2_1_t2i-api.json` | | `WORKFLOW_ACE_STEP_PATH` | 音乐生成工作流文件名 | `audio_ace_step_1_5_xl_sft_api.json` | 工作流文件位于 `workflow-api/` 目录。 ## 使用方法 ### 启动 MCP 服务器 ```bash python main.py ``` 服务器将在 `http://localhost:8002` 启动,使用 SSE 传输协议。 ### 工具调用 #### 1. 图像生成工具 `generate_image` ```python from fastmcp import Client async with Client("http://localhost:8002") as client: result = await client.call_tool( "generate_image", { "prompt": "一只可爱的猫咪在花园里玩耍", "negative": "模糊, 低质量", "width": 1024, "height": 768, "cfg": 4.0, "steps": 30, "file_name": "cat.png" } ) print(result) ``` **参数说明:** - `prompt` (str):图像生成提示词 - `negative` (str):负面提示词 - `width` (int):图像宽度,默认 768 - `height` (int):图像高度,默认 1368 - `cfg` (float):引导缩放系数,默认 4.0 - `steps` (int):推理步数,默认 30 - `file_name` (str):自定义文件名(可选) #### 2. 音乐生成工具 `generate_music` ```python from fastmcp import Client async with Client("http://localhost:8002") as client: result = await client.call_tool( "generate_music", { "lyrics": "《新年快乐》\n新年快乐 新年快乐\n愿你笑容像花儿一样盛开", "style": "调性:G大调,速度:BPM 110,曲风:流行民谣\n人声:明亮女声,温暖音色,中文歌词\n编曲:钢琴、原声吉他、轻打击乐、贝斯\n情绪:欢乐、庆祝、充满希望、新年氛围\n结构:[前奏:4小节钢琴与吉他] [主歌1] [副歌] [主歌2] [副歌] [桥段] [副歌] [尾奏:渐弱]", "bpm": 110, "keyscale": "G major", "language": "zh", "cfg_scale": 4, "file_name": "happy_new_year.mp3" } ) print(result) ``` **参数说明:** - `lyrics` (str):歌词内容,支持段落标记(如 Verse、Chorus) - `style` (str):音乐风格描述,包含调性、速度、曲风、人声、编曲、情绪、结构 - `bpm` (int):节拍数(每分钟节拍数),默认 120 - `keyscale` (str):调性(如 "C major"、"G major"),可选 - `language` (str):语言(如 "zh"、"en"),默认 "zh",可选 - `cfg_scale` (float):引导缩放系数,默认 4,可选 - `file_name` (str):自定义文件名(可选) ## 项目结构 ``` comfyui-mcp/ ├── main.py # MCP 服务器入口 ├── pyproject.toml # 项目配置和依赖 ├── README.md # 项目文档 ├── COMFYUI_API_GUIDE.md # ComfyUI API 调用指南 ├── .env # 环境变量配置 ├── .gitignore # Git 忽略文件 ├── .python-version # Python 版本配置 ├── LICENSE # 许可证文件 ├── uv.lock # uv 依赖锁定文件 ├── output/ # 生成文件输出目录 │ ├── *.png # 生成的图像 │ ├── *.mp3 # 生成的音频 ├── skills/ # OpenCode 技能目录 │ ├── text-to-image/ # 图像生成技能 │ │ └── SKILL.md # 技能说明文件 │ └── text-to-music/ # 音乐生成技能 │ └── SKILL.md # 技能说明文件 ├── snapshots/ # 工作流截图 │ ├── qwen-image.png # 图像生成工作流截图 │ └── ace-step-workflow.png # 音乐生成工作流截图 ├── workflow-api/ # ComfyUI API 工作流文件 │ ├── image_qwen_image_2_1_t2i-api.json # 图像生成 API 工作流 │ └── audio_ace_step_1_5_xl_sft_api.json # 音乐生成 API 工作流 └── src/ ├── run_qwen_image.py # 图像生成工作流执行器 ├── run_ace_step.py # 音乐生成工作流执行器 └── utils.py # 工具函数(队列、下载等) ``` ## ComfyUI工作流说明 ### 图像生成工作流 - **模型**:Qwen Image 2.1 (qwen_image_2.1_bf16.safetensors) - **VAE**:qwen_image_2.1_vae_bf16.safetensors - **CLIP**:qwen3vl_8b_bf16.safetensors ### 音乐生成工作流 - **模型**:Ace Step 1.5 XL SFT (acestep_v1.5_xl_sft_bf16.safetensors) - **VAE**:ace_1.5_vae.safetensors - **CLIP**:qwen_0.6b_ace15.safetensors + qwen_4b_ace15.safetensors - **采样器**:dpm_2_ancestral - **调度器**:karras - **默认参数**:BPM 120, E major ![音乐生成工作流](snapshots/ace-step-workflow.png) ## 输出文件 生成的文件保存在项目根目录的 `output/` 文件夹: - **图像**:PNG 格式,保存在 `output/` 目录 - **音频**:MP3 格式 (320kbps),保存在 `output/` 目录 ## 专辑展示页 项目包含一个专辑展示网页 (`web/index.html`),用于展示生成的音乐作品和封面艺术。 **功能特色:** - 🎵 **音乐播放器** — 支持播放/暂停、进度条控制、时间显示 - 📝 **歌词展示** — 精美排版的歌词内容 - 🖼️ **封面画廊** — 点击图片可放大查看 - ✨ **精致设计** — 暖色调主题、优雅字体、滚动动画 **访问方式:** ```bash # 在浏览器中打开 start web/index.html ``` ![专辑展示页](web/image.png) ## 相关资源 - [ComfyUI 官方文档](https://github.com/comfyanonymous/ComfyUI) - [FastMCP 文档](https://github.com/jlowin/fastmcp) - [ComfyUI API 调用指南](COMFYUI_API_GUIDE.md) ## 相关技能 本项目可以与以下 OpenCode 技能配合使用,以增强图像和音乐生成体验: - [**text-to-image**](skills/text-to-image/SKILL.md):专业文生图提示词设计与优化,支持多种风格和场景的图像生成 - [**text-to-music**](skills/text-to-music/SKILL.md):专业音乐提示词设计与优化,支持多种风格和情感的音乐生成 这些技能提供了详细的参数最佳实践和提示词优化技巧,可帮助您更好地使用本项目的生成功能。 ## 许可证 本项目采用 MIT 许可证,详见 LICENSE 文件。