{"id":35094131,"url":"https://github.com/joenorton/comfyui-mcp-server","last_synced_at":"2026-01-20T21:09:35.175Z","repository":{"id":280914419,"uuid":"943574915","full_name":"joenorton/comfyui-mcp-server","owner":"joenorton","description":"lightweight Python-based MCP (Model Context Protocol) server for local ComfyUI","archived":false,"fork":false,"pushed_at":"2026-01-19T06:26:35.000Z","size":279,"stargazers_count":164,"open_issues_count":2,"forks_count":39,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-19T14:51:00.691Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joenorton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-05T23:40:05.000Z","updated_at":"2026-01-19T06:26:39.000Z","dependencies_parsed_at":"2025-03-06T01:35:04.551Z","dependency_job_id":"4bfdf79a-2843-4bae-9a25-bd2ea2c6f528","html_url":"https://github.com/joenorton/comfyui-mcp-server","commit_stats":null,"previous_names":["joenorton/comfyui-mcp-server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/joenorton/comfyui-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joenorton%2Fcomfyui-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joenorton%2Fcomfyui-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joenorton%2Fcomfyui-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joenorton%2Fcomfyui-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joenorton","download_url":"https://codeload.github.com/joenorton/comfyui-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joenorton%2Fcomfyui-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28613772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T18:56:40.769Z","status":"ssl_error","status_checked_at":"2026-01-20T18:54:26.653Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-27T15:04:24.312Z","updated_at":"2026-01-20T21:09:35.169Z","avatar_url":"https://github.com/joenorton.png","language":"Python","funding_links":[],"categories":["MCP Servers for Creative Work","📚 Projects (1974 total)","App"],"sub_categories":["Image, Video, Audio Generation","MCP Servers"],"readme":"# ComfyUI MCP Server\n\n\u003e Generate and refine AI images/audio/video through natural conversation\n\nA lightweight MCP (Model Context Protocol) server that lets AI agents generate and iteratively refine images, audio, and video using a local ComfyUI instance.\n\nYou run the server, connect a client, and issue tool calls. Everything else is optional depth.\n\n---\n\n## Quick Start (2–3 minutes)\n\nThis proves everything is working.\n\n### 1) Clone and set up\n\n```bash\ngit clone https://github.com/joenorton/comfyui-mcp-server.git\ncd comfyui-mcp-server\npip install -r requirements.txt\n```\n\n### 2) Start ComfyUI\n\nMake sure ComfyUI is installed and running locally.\n\n```bash\ncd \u003cComfyUI_dir\u003e\npython main.py --port 8188\n```\n\n### 3) Run the MCP server\n\nFrom the repository directory:\n\n```bash\npython server.py\n```\n\nThe server listens at:\n\n```\nhttp://127.0.0.1:9000/mcp\n```\n\n### 4) Verify it works (no AI client required)\n\nRun the included test client:\n\n```bash\n# Use default prompt\npython test_client.py\n\n# Or provide your own prompt\npython test_client.py -p \"a beautiful sunset over mountains\"\npython test_client.py --prompt \"a cat on a mat\"\n```\n\n`test_client.py` will:\n\n* connect to the MCP server\n* list available tools\n* fetch and display server defaults (width, height, steps, model, etc.)\n* run `generate_image` with your prompt (or a default)\n* automatically use server defaults for all other parameters\n* print the resulting asset information\n\nIf this step succeeds, the system is working.\n\n**Note:** The test client respects server defaults configured via config files, environment variables, or `set_defaults` calls. Only the `prompt` parameter is required; all other parameters use server defaults automatically.\n\nThat’s it.\n\n---\n\n## Use with an AI Agent (Cursor / Claude / n8n)\n\nOnce the server is running, you can connect it to an AI client.\n\nCreate a project-scoped `.mcp.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"comfyui-mcp-server\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"http://127.0.0.1:9000/mcp\"\n    }\n  }\n}\n```\n\n**Note:** Some clients use `\"type\": \"http\"` instead of `\"streamable-http\"`. Both work with this server. If auto-discovery doesn't work, try changing the type field.\n\nRestart your AI client. You can now call tools such as:\n\n* `generate_image`\n* `view_image`\n* `regenerate`\n* `get_job`\n* `list_assets`\n\nThis is the primary intended usage mode.\n\n---\n\n## What You Can Do After It Works\n\nOnce you’ve confirmed the server runs and a client can connect, the system supports:\n\n* Iterative refinement via `regenerate` (no re-prompting)\n* Explicit asset identity for reliable follow-ups\n* Job polling and cancellation for long-running generations\n* Optional image injection into the AI’s context (`view_image`)\n* Auto-discovered ComfyUI workflows with parameter exposure\n* Configurable defaults to avoid repeating common settings\n\nEverything below builds on the same basic loop you just tested.\n\n## Migration Notes (Previous Versions)\n\nIf you’ve used earlier versions of this project, a few things have changed.\n\n### What’s the Same\n- You still run a local MCP server that delegates execution to ComfyUI\n- Workflows are still JSON files placed in the `workflows/` directory\n- Image generation behavior is unchanged at its core\n\n### What’s New\n- **Streamable HTTP transport** replaces the older WebSocket-based approach\n- **Explicit job management** (`get_job`, `get_queue_status`, `cancel_job`)\n- **Asset identity** instead of ad-hoc URLs (stable across hostname changes)\n- **Iteration support** via `regenerate` (replay with parameter overrides)\n- **Optional visual feedback** for agents via `view_image`\n- **Configurable defaults** to avoid repeating common parameters\n\n### What Changed Conceptually\nEarlier versions were a thin request/response bridge.\nThe current version is built around **iteration** and **stateful control loops**.\n\nYou can still generate an image with a single call, but you now have the option to:\n- refer back to specific outputs\n- refine results without re-specifying everything\n- poll and cancel long-running jobs\n- let AI agents inspect generated images directly\n\n### Looking for the Old Behavior?\nIf you want the minimal, single-shot behavior from earlier versions:\n- run `test_client.py` (this mirrors the original usage pattern)\n- call `generate_image` with just a prompt (server defaults handle the rest)\n- ignore the additional tools\n\nNo migration is required unless you want the new capabilities.\n\n## Available Tools\n\n### Generation Tools\n\n- **`generate_image`**: Generate images (requires `prompt`)\n- **`generate_song`**: Generate audio (requires `tags` and `lyrics`)\n- **`regenerate`**: Regenerate an existing asset with optional parameter overrides (requires `asset_id`)\n\n### Viewing Tools\n\n- **`view_image`**: View generated images inline (images only, not audio/video)\n\n### Job Management Tools\n\n- **`get_queue_status`**: Check ComfyUI queue state (running/pending jobs) - provides async awareness\n- **`get_job`**: Poll job completion status by prompt_id - check if a job has finished\n- **`list_assets`**: Browse recently generated assets - enables AI memory and iteration\n- **`get_asset_metadata`**: Get full provenance and parameters for an asset - includes workflow history\n- **`cancel_job`**: Cancel a queued or running job\n\n### Configuration Tools\n\n- **`list_models`**: List available ComfyUI models\n- **`get_defaults`**: Get current default values\n- **`set_defaults`**: Set default values (with optional persistence)\n\n### Workflow Tools\n\n- **`list_workflows`**: List all available workflows\n- **`run_workflow`**: Run any workflow with custom parameters\n\n### Publish Tools\n\n- **`get_publish_info`**: Show publish status (detected project root, publish dir, ComfyUI output root, and any missing setup)\n- **`set_comfyui_output_root`**: Set ComfyUI output directory (recommended for Comfy Desktop / nonstandard installs; persisted across restarts)\n- **`publish_asset`**: Publish a generated asset into the project's web directory with deterministic compression (default 600KB)\n\n**Publish Notes:**\n- **Session-scoped**: `asset_id`s are valid only for the current server session; restart invalidates them.\n- **Zero-config in common cases**: Publish dir auto-detected (`public/gen`, `static/gen`, or `assets/gen`); if ComfyUI output can't be detected, set it once via `set_comfyui_output_root`.\n- **Two modes**: Demo (explicit filename) and Library (auto filename + manifest update). In library mode, `manifest_key` is required.\n- **Manifest**: Updated only when `manifest_key` is provided.\n- **Compression**: Deterministic ladder to meet size limits; fails with a clear error if it can't.\n\n**Quick Start:**\n\nExample agent conversation flow:\n\n**User:** \"Generate a hero image for my website and publish it as hero.webp\"\n\n**Agent:** *Checks publish configuration*\n- Calls `get_publish_info()` → sees status \"ready\"\n\n**Agent:** *Generates image*\n- Calls `generate_image(prompt=\"a hero image for a website\")` → gets `asset_id`\n\n**Agent:** *Publishes asset*\n- Calls `publish_asset(asset_id=\"...\", target_filename=\"hero.webp\")` → success\n\n**User:** \"Now generate a logo and add it to the manifest as 'site-logo'\"\n\n**Agent:** *Generates and publishes with manifest*\n- Calls `generate_image(prompt=\"a modern logo\")` → gets `asset_id`\n- Calls `publish_asset(asset_id=\"...\", manifest_key=\"site-logo\")` → auto-generates filename, updates manifest\n\nSee [docs/HOW_TO_TEST_PUBLISH.md](docs/HOW_TO_TEST_PUBLISH.md) for detailed usage and testing instructions.\n\n## Custom Workflows\n\nAdd custom workflows by placing JSON files in the `workflows/` directory. Workflows are automatically discovered and exposed as MCP tools.\n\n### Workflow Placeholders\n\nUse `PARAM_*` placeholders in workflow JSON to expose parameters:\n\n- `PARAM_PROMPT` → `prompt: str` (required)\n- `PARAM_INT_STEPS` → `steps: int` (optional)\n- `PARAM_FLOAT_CFG` → `cfg: float` (optional)\n\n**Example:**\n```json\n{\n  \"3\": {\n    \"inputs\": {\n      \"text\": \"PARAM_PROMPT\",\n      \"steps\": \"PARAM_INT_STEPS\"\n    }\n  }\n}\n```\n\nThe tool name is derived from the filename (e.g., `my_workflow.json` → `my_workflow` tool).\n\n---\n\n## Configuration\n\nThe server supports configurable defaults to avoid repeating common parameters. Defaults can be set via:\n\n- **Runtime defaults**: Use `set_defaults` tool (ephemeral, lost on restart)\n- **Config file**: `~/.config/comfy-mcp/config.json` (persistent)\n- **Environment variables**: `COMFY_MCP_DEFAULT_*` prefixed variables\n\nDefaults are resolved in priority order: per-call values → runtime defaults → config file → environment variables → hardcoded defaults.\n\nFor complete configuration details, see [docs/REFERENCE.md](docs/REFERENCE.md#parameters).\n\n---\n\n## Detailed Reference\n\nComplete parameter lists, return schemas, configuration options, and advanced workflow metadata are documented in:\n\n- **[API Reference](docs/REFERENCE.md)** - Complete tool reference, parameters, return values, and configuration\n- **[Architecture](docs/ARCHITECTURE.md)** - Design decisions and system overview\n\n## Project Structure\n\n```\ncomfyui-mcp-server/\n├── server.py              # Main entry point\n├── comfyui_client.py      # ComfyUI API client\n├── asset_processor.py     # Image processing utilities\n├── test_client.py         # Test client\n├── managers/              # Core managers\n│   ├── workflow_manager.py\n│   ├── defaults_manager.py\n│   └── asset_registry.py\n├── tools/                 # MCP tool implementations\n│   ├── generation.py\n│   ├── asset.py\n│   ├── job.py             # Job management tools\n│   ├── configuration.py\n│   └── workflow.py\n├── models/                # Data models\n│   ├── workflow.py\n│   └── asset.py\n└── workflows/             # Workflow JSON files\n    ├── generate_image.json\n    └── generate_song.json\n```\n\n## Notes\n\n- The server binds to localhost by default. Do not expose it publicly without authentication or a reverse proxy.\n- Ensure your models exist in `\u003cComfyUI_dir\u003e/models/checkpoints/`\n- Server uses **streamable-http** transport (HTTP-based, not WebSocket)\n- Workflows are auto-discovered - no code changes needed\n- Assets expire after 24 hours (configurable)\n- `view_image` only supports images (PNG, JPEG, WebP, GIF)\n- Asset identity uses `(filename, subfolder, type)` instead of URL for robustness\n- Full workflow history is stored for provenance and reproducibility\n- `regenerate` uses stored workflow data to recreate assets with parameter overrides\n- Session isolation: `list_assets` can filter by session for clean AI agent context\n\n## Troubleshooting\n\n**Server won't start:**\n- Check ComfyUI is running on port 8188 (default)\n- Verify Python 3.8+ is installed (`python --version`)\n- Check all dependencies are installed: `pip install -r requirements.txt`\n- Check server logs for specific error messages\n\n**Client can't connect:**\n- Verify server shows \"Server running at http://127.0.0.1:9000/mcp\" in the console\n- Test server directly: `curl http://127.0.0.1:9000/mcp` (should return MCP response)\n- Check `.mcp.json` is in project root (or correct location for your client)\n- Try both `\"type\": \"streamable-http\"` and `\"type\": \"http\"` - both are supported\n- For Cursor-specific issues, see [docs/MCP_CONFIG_README.md](docs/MCP_CONFIG_README.md)\n\n**Tools not appearing:**\n- Check `workflows/` directory has JSON files with `PARAM_*` placeholders\n- Check server logs for workflow parsing errors\n- Verify ComfyUI has required custom nodes installed (if using custom workflows)\n- Restart the MCP server after adding new workflows\n\n**Asset not found errors:**\n- Assets expire after 24 hours by default (configurable via `COMFY_MCP_ASSET_TTL_HOURS`)\n- Assets are lost on server restart (ephemeral by design)\n- Use `get_asset_metadata` to verify asset exists before using `regenerate`\n- Check server logs to see if asset was registered successfully\n\n## Known Limitations (v1.0)\n\n- **Ephemeral asset registry**: `asset_id` references are only valid while the MCP server is running (and until TTL expiry). After restart, previously-issued `asset_id`s can’t be resolved, and regenerate will fail for those assets.\n\n## Contributing\n\nIssues and pull requests are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\n## Acknowledgements\n\n- [@venetanji](https://github.com/venetanji) - streamable-http foundation \u0026 PARAM_* system\n\n## Maintainer\n[@joenorton](https://github.com/joenorton)\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoenorton%2Fcomfyui-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoenorton%2Fcomfyui-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoenorton%2Fcomfyui-mcp-server/lists"}