{
  "markdown": "# comfyui-mcp\n\nMCP server for [ComfyUI](https://github.com/comfyanonymous/ComfyUI). Generate images from natural language prompts in any MCP-compatible client.\n\n[![comfyui-mcp MCP server](https://glama.ai/mcp/servers/miller-joe/comfyui-mcp/badges/card.svg)](https://glama.ai/mcp/servers/miller-joe/comfyui-mcp)\n\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/miller-joe?style=social&logo=github)](https://github.com/sponsors/miller-joe)\n[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-ff5e5b?logo=kofi&logoColor=white)](https://ko-fi.com/indivisionjoe)\n\n## Status\n\nv0.2 ships the core tools plus upscale, an image proxy, and public-URL support. Current tool surface: `generate_image`, `generate_variations`, `generate_with_workflow`, `refine_image`, `upscale_image`, `list_models`, `list_workflows`, `upload_image`, `generate_with_controlnet`, `generate_with_ip_adapter`, plus a workflow template registry. See Roadmap for what's next.\n\n## Install\n\n### npx (no install required)\n\n```bash\nnpx @miller-joe/comfyui-mcp --comfyui-url http://your-comfyui-host:8188\n```\n\n### npm\n\n```bash\nnpm install -g @miller-joe/comfyui-mcp\ncomfyui-mcp --comfyui-url http://your-comfyui-host:8188\n```\n\n### Docker\n\n```bash\ndocker run -p 9100:9100 \\\n  -e COMFYUI_URL=http://your-comfyui-host:8188 \\\n  ghcr.io/miller-joe/comfyui-mcp:latest\n```\n\n## Connect an MCP client\n\nClaude Code:\n\n```bash\nclaude mcp add --transport http comfyui http://localhost:9100/mcp\n```\n\nOr register the streamable HTTP endpoint with an MCP gateway (e.g. MetaMCP) to aggregate with other servers.\n\n## Configuration\n\nAll options can be set via CLI flag or environment variable:\n\n| CLI flag | Env var | Default | Description |\n|---|---|---|---|\n| `--host` | `MCP_HOST` | `0.0.0.0` | Bind host (HTTP mode only) |\n| `--port` | `MCP_PORT` | `9100` | Bind port (HTTP mode only) |\n| `--stdio` | `MCP_TRANSPORT=stdio` | (unset) | Speak MCP over stdio instead of HTTP. Use when launched as a subprocess by a stdio-first MCP client (Claude Desktop, mcp-inspector). |\n| `--comfyui-url` | `COMFYUI_URL` | `http://127.0.0.1:8188` | ComfyUI HTTP URL used internally by this server |\n| `--comfyui-public-url` | `COMFYUI_PUBLIC_URL` | same as `--comfyui-url` | External URL in image URLs returned to clients. Set this when the internal URL is not reachable from MCP clients (common with Docker networks). |\n| (no flag) | `COMFYUI_DEFAULT_CKPT` | `sd_xl_base_1.0.safetensors` | Default checkpoint filename |\n\n### Transports\n\nThe server speaks streamable HTTP by default (great for Claude Code, MetaMCP, raw `fetch`). Pass `--stdio` (or set `MCP_TRANSPORT=stdio`) to switch into stdio mode, which is what stdio-first clients like Claude Desktop and the MCP Inspector expect:\n\n```bash\n# Claude Desktop config (claude_desktop_config.json):\n{\n  \"mcpServers\": {\n    \"comfyui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@miller-joe/comfyui-mcp\", \"--stdio\", \"--comfyui-url\", \"http://127.0.0.1:8188\"]\n    }\n  }\n}\n```\n\n### Image URLs returned to clients\n\nGeneration tools return image URLs like `<comfyui-public-url>/view?filename=…`. If `--comfyui-public-url` is not set, URLs use the internal `--comfyui-url` value.\n\nThe server also exposes a proxy endpoint: `GET /images/<filename>?subfolder=&type=output` streams the image bytes through this server, which is useful when clients can reach the MCP server but not ComfyUI directly.\n\nThe default checkpoint must match a file in your ComfyUI `models/checkpoints/` directory. Override via `COMFYUI_DEFAULT_CKPT` or pass `checkpoint` as a tool argument.\n\n## Tools\n\n### `generate_image`\n\nGenerate an image from a text prompt using ComfyUI's default txt2img workflow.\n\nParameters: `prompt` (required), `negative_prompt`, `width`, `height`, `steps`, `cfg`, `seed`, `checkpoint`.\n\n### `generate_variations`\n\nGenerate multiple variations of the same prompt by varying the seed. Returns all images at once.\n\nParameters: `prompt` (required), `count` (2–16, default 4), plus the same generation params as `generate_image`, with `base_seed` instead of `seed`.\n\n### `generate_with_workflow`\n\nSubmit an arbitrary ComfyUI workflow JSON (full node graph) and return the resulting image URLs. Use this for custom workflows — ControlNet, upscaling, or anything exported from ComfyUI's **Save (API Format)**.\n\nParameter: `workflow` (object), the complete node graph.\n\n### `refine_image`\n\nRun img2img on a source image. The server fetches a source URL, uploads it to ComfyUI, and runs a denoising pass guided by a new prompt. Lower `denoise` preserves more of the original; higher gives the prompt more freedom.\n\nParameters: `prompt`, `source_image_url` (required), `denoise` (0–1, default 0.5), plus standard generation params.\n\n### `list_models`\n\nList available checkpoints, LoRAs, samplers, or schedulers on the ComfyUI instance.\n\nParameter: `kind`, one of `checkpoints` (default), `loras`, `samplers`, `schedulers`.\n\n### `list_workflows`\n\nList built-in workflow templates shipped with this server (currently `txt2img`, `img2img`, `upscale`, `controlnet`, `ip_adapter`).\n\n### `upload_image`\n\nUpload a reference image to ComfyUI for use in img2img, ControlNet, or IP-Adapter workflows.\n\nParameters: `source_url` or `image_base64` (one required), `filename` (optional), `overwrite` (default false).\n\nReturns: the stored filename, which can be used as the `image` input in workflow nodes like `LoadImage`.\n\n### `generate_with_controlnet`\n\nGenerate an image conditioned by a ControlNet preprocessed image (pose skeleton, depth map, canny edges, normal map, etc.) plus a text prompt.\n\nParameters: `prompt`, `control_image_url` (the preprocessed conditioning image; this tool doesn't run preprocessors), `controlnet_model` (filename from `models/controlnet/`), `strength` (0–2, default 1), `start_percent` / `end_percent` (0–1, controlling when CN is active during sampling), plus standard generation params.\n\nRequires a ControlNet model installed in your ComfyUI `models/controlnet/` directory.\n\n### `generate_with_ip_adapter`\n\nGenerate an image using a reference image as a visual/style/subject guide via IP-Adapter.\n\nParameters: `prompt`, `reference_image_url`, `preset` (e.g. `\"STANDARD (medium strength)\"`, `\"PLUS FACE (portraits)\"`, `\"VIT-G (medium strength)\"`), `weight` (0–3, default 1), `start_at` / `end_at` (0–1), plus standard generation params.\n\nRequires the [ComfyUI-IPAdapter-plus](https://github.com/cubiq/ComfyUI_IPAdapter_plus) custom node pack plus the preset's matching IPAdapter weights and CLIP Vision models.\n\n### Workflow template registry\n\nSave complex workflow JSON once, run by name later. Templates are stored on disk under `--templates-dir` (defaults to `~/.config/comfyui-mcp/templates/<name>.json`) so they survive restarts and are portable across MCP clients.\n\n| Tool | Description |\n|---|---|\n| `save_workflow_template` | Save a workflow JSON under a named slot. `overwrite=true` to replace. |\n| `list_workflow_templates` | List saved templates with descriptions and last-updated timestamp. |\n| `get_workflow_template` | Fetch a stored template's JSON plus metadata. |\n| `delete_workflow_template` | Delete a stored template. |\n| `run_workflow_template` | Run a saved template against ComfyUI and return image URLs. |\n\nTemplate names must start alphanumeric. Allowed: `a-z`, `A-Z`, `0-9`, `-`, `_`. Max 64 chars.\n\n### Return format\n\nAll generation tools return image URLs served directly by the ComfyUI instance (`http://<comfyui>/view?filename=…`). These URLs can be passed straight to any client that accepts image URLs.\n\n## Architecture\n\n```\n┌────────────────┐     ┌──────────────────┐     ┌──────────────┐\n│  MCP client    │────▶│  comfyui-mcp     │────▶│  ComfyUI     │\n│  (Claude, etc.)│◀────│  (this server)   │◀────│  instance    │\n└────────────────┘     └──────────────────┘     └──────────────┘\n     streamable HTTP        HTTP REST + poll\n```\n\nThe server is stateless. A single MCP request submits a workflow to ComfyUI, polls `/history/{id}` until complete, and returns image URLs.\n\n## Development\n\n```bash\ngit clone https://github.com/miller-joe/comfyui-mcp\ncd comfyui-mcp\nnpm install\nnpm run dev       # hot-reload via tsx watch\nnpm run build     # compile TS to dist/\nnpm run typecheck # strict type checking\n```\n\nRequires Node 20+.\n\n## Roadmap\n\nShipped in v0.2:\n\n- `generate_image`, `generate_variations`, `generate_with_workflow`\n- `refine_image` (img2img from a source URL)\n- `upscale_image` (ESRGAN / SwinIR-style model upscale)\n- `list_models`, `list_workflows`, `upload_image`\n- Image proxy endpoint (`/images/<filename>`) for clients that can't reach ComfyUI directly\n- Configurable public URL for externally-correct image URLs\n- Workflow template registry (save/list/get/delete/run)\n- `generate_with_controlnet` (requires ControlNet models on the ComfyUI side)\n- `generate_with_ip_adapter` (requires ComfyUI-IPAdapter-plus pack)\n\nPlanned:\n\n- WebSocket progress events for long-running generations.\n\n## License\n\nMIT © Joe Miller\n\n## Support\n\nIf this tool saves you time, consider supporting development:\n\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/miller-joe?style=social&logo=github)](https://github.com/sponsors/miller-joe)\n[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-ff5e5b?logo=kofi&logoColor=white)](https://ko-fi.com/indivisionjoe)\n\nEvery contribution funds maintenance, documentation, and the next release.\n",
  "bytes": 9374,
  "sha": "824874aee6ad818b03fdaf07e005005ba26a8b0f2e735cd11858ca50cf47669b",
  "repo_slug": "miller-joe/comfyui-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_miller_joe_comfyui_mcp_3bcb155c/readme"
}