RunComfy MCP Server

MCP server to generate AI videos and images using the RunComfy APIs.

Setup

1. Install dependencies:

cd mcp-servers/runcomfy
bun install

2. Get your API key from: https://www.runcomfy.com/profile

3. Add the configuration to your ~/.windsurf/mcp_config.json:

{
  "mcpServers": {
    "runcomfy": {
      "command": "bun",
      "args": [".../mcp-runcomfy/index.js"],
      "env": {
        "RUNCOMFY_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

4. Restart Windsurf

Available tools

runcomfy_generate_video

Generate an AI video. Parameters:

• prompt (required): Video description

• model: wan-2.1, wan-2.1-720p, animatediff, svd, kling, minimax

• image_url: Image URL for image-to-video models

• duration: Duration in seconds

• aspect_ratio: 16:9, 9:16, 1:1

• seed: Seed for reproducibility

runcomfy_generate_image

Generate an AI image (text-to-image). Parameters:

• prompt (required): Image description

• model: flux-2-pro

• aspect_ratio: 16:9, 9:16, 1:1

• seed: Seed for reproducibility

• inputs: Advanced model-specific inputs (object)

runcomfy_edit_image

Edit an image (image-to-image). Parameters:

• prompt (required): Edit instruction

• model: flux-2-dev-edit, flux-kontext-pro-edit, qwen-edit-next-scene

• image_url: Single image URL (some models)

• image_urls: Multiple image URLs (some models)

• aspect_ratio: 16:9, 9:16, 1:1

• seed: Seed for reproducibility

• inputs: Advanced model-specific inputs (object)

runcomfy_check_status

Check the status of a request.

runcomfy_get_result

Get the result (video URL) of a completed request.

runcomfy_cancel

Cancel a queued request.

runcomfy_list_models

List available models plus curated alias maps for video and image.

runcomfy_download_media

Download a generated media to local disk. Parameters:

• url: Direct HTTPS URL to the media file

• request_id: Resolve the media URL from a completed request (via /v1/requests/{request_id}/result)

• kind: Preferred output kind when resolving from request_id (image or video)

• index: Optional index if multiple outputs exist (0-based)

• output_dir: Directory to save into (defaults to a temp folder)

• filename: Optional filename override

• overwrite: Overwrite if file exists (default false)

• return_mode: How to return the downloaded media (default path)

  • path: Return only JSON with saved_path

  • resource_link: Also return a resource_link pointing to file://...

  • embedded: Also return an embedded resource with base64 blob

Usage example

// Generate video
runcomfy_generate_video({
  prompt: "A calm person breathing slowly, teal glow, dark background",
  model: "wan-2.1",
  aspect_ratio: "1:1"
})

// Check status
runcomfy_check_status({ request_id: "abc123" })

// Get result
runcomfy_get_result({ request_id: "abc123" })

// Generate image
runcomfy_generate_image({
  prompt: "A minimal flat illustration of a calm person breathing, teal and navy",
  model: "flux-2-pro",
  aspect_ratio: "1:1"
})

// Edit image
runcomfy_edit_image({
  prompt: "Change the background to a dark gradient and add a subtle teal glow",
  model: "flux-2-dev-edit",
  image_urls: ["https://example.com/input.png"]
})

// Download result media by URL
runcomfy_download_media({
  url: "https://example.com/output.png",
  output_dir: "/tmp",
  filename: "output.png",
  overwrite: true
})

// Download result media by request_id
runcomfy_download_media({
  request_id: "abc123",
  kind: "image",
  index: 0
})

// Download and return a resource_link
runcomfy_download_media({
  request_id: "abc123",
  kind: "image",
  return_mode: "resource_link"
})

// Download and return an embedded base64 resource
runcomfy_download_media({
  request_id: "abc123",
  kind: "image",
  return_mode: "embedded"
})