freebeat-mcp

freebeat-mcp

MCP server for Freebeat creative workflows.

Use it from MCP clients such as Claude Desktop and Cursor through npx freebeat-mcp.

It currently supports audio and image upload, effect template discovery, AI effect generation, AI music video generation, Open RPC image/video generation, model discovery, and async task polling.

Features

• Local audio upload or source URL import
• Image upload for workflows that accept reference images
• Supported effect template listing
• AI effect generation
• AI music video generation
• Supported image and video model discovery
• AI image generation and single-image editing
• AI text-to-video generation
• Generic task polling and result retrieval

Installation

Run the server through npm without a separate install step:

npx -y freebeat-mcp

Prerequisites

• Get your API key from freebeat.ai.
• Use an MCP client such as Claude Desktop or Cursor.

Configuration

Claude Desktop

{
  "mcpServers": {
    "freebeat": {
      "command": "npx",
      "args": ["-y", "freebeat-mcp"],
      "env": {
        "FREEBEAT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "freebeat": {
      "command": "npx",
      "args": ["-y", "freebeat-mcp"],
      "env": {
        "FREEBEAT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
FREEBEAT_API_KEY	Yes	API authentication key

This package depends on Freebeat online services. Available source platforms, effect templates, and generation capabilities may change with backend updates.

Tools

upload_audio

Upload a local audio file or import from a music platform URL.

Currently supported platforms:

• SoundCloud
• YouTube
• Suno
• Udio
• TikTok
• Stable Audio
• Riffusion

Provide exactly one of file_path or url.

Returns a music_id that can be used by either generate_music_video or generate_effect.

upload_image

Upload one or two images and receive image_urls.

For MV generation, pass the returned image_urls into generate_music_video.reference_image_urls.

For effect generation, the default recommendation is still list_effects.image_url, but you can also upload one image and pass image_urls[0] into generate_effect.reference_image_urls.

list_effects

List supported effects with:

• effect_id
• display_name
• image_url
• preview_video_url
• default_music_id
• default_music_name
• aspect_ratio

For effect generation, pass:

• effect_id into generate_effect.effect_id
• default_music_id into generate_effect.music_id
• image_url as the default single entry in generate_effect.reference_image_urls

You can use the built-in effect image directly, or replace it with a single uploaded image URL from upload_image.

generate_effect

Start an async effect generation task.

Recommended flow:

• list_effects
• optional upload_audio if you want to replace the effect's default music
• optional upload_image if you want to replace the effect's default image
• generate_effect
• get_task_status
• get_task_result only after status is completed

Parameters:

• effect_id required
• music_id required, usually default_music_id from list_effects, or a music_id from upload_audio if you want to replace it
• prompt required, trimmed length must be 1 to 2000
• watermark optional, default false
• reference_image_urls required and must contain exactly one image URL; recommended default is list_effects.image_url, but you can also use upload_image.image_urls[0]

Returns a task envelope with:

• task_id
• task_type currently effect_generation
• status

generate_music_video

Start an async MV generation task from a music_id returned by upload_audio.

Recommended flow:

• upload_audio
• optional upload_image
• generate_music_video
• get_task_status
• get_task_result only after status is completed

Parameters:

• music_id required, from upload_audio
• prompt required, trimmed length must be 1 to 2000
• mv_type optional, default abstract
• style optional
• aspect_ratio optional, default 16:9
• resolution optional, default 720
• watermark optional, default false
• start_ms optional
• end_ms optional
• reference_image_urls optional

Returns a task envelope with:

• task_id
• task_type currently music_video_generation
• status

list_models

List supported Open RPC models for either image or video.

Recommended flow:

• list_models with type: "image" before generate_image or edit_image
• list_models with type: "video" before generate_video
• optional get_model_help for model-specific examples and constraints

Each model entry includes:

• model_id
• model, the API model key when one is available
• display_name
• commands
• constraints

get_model_help

Show detailed usage guidance for one Open RPC model.

Parameters:

• model required, using either a numeric model_id or API model key from list_models

Use this before video generation to confirm required duration, resolution, supported aspect_ratio, and whether generate_audio is supported. For video models, help also lists supported generation modes (text, image, transition, reference) and duration values by resolution when the local catalog has that detail.

generate_image

Create an async Open RPC image generation batch.

Recommended flow:

• list_models with type: "image"
• optional get_model_help
• generate_image
• get_task_status with the returned batch_id

Parameters:

• model required, from list_models
• prompt required, trimmed length must be 1 to 2000
• size optional
• resolution optional
• quality optional
• output_format optional, for supported models such as png, jpeg, or webp
• custom_resolution optional, only accepted for models that support custom pixel dimensions
• count optional, default 1

For GPT-Image 1.5 (model_id 70) and GPT-Image 2 (model_id 108), the MCP server sends quality: "medium" and resolution: "1024x1024" by default when omitted. GPT-Image 1.5 currently accepts resolution values 1024x1024, 1536x1024, and 1024x1536; GPT-Image 2 exposes its broader list through get_model_help. If resolution is omitted but size is provided, that size is also sent as resolution for compatibility.

edit_image

Create an async Open RPC single-image edit batch.

Recommended flow:

• upload_image or provide an existing image URL
• list_models with type: "image"
• optional get_model_help
• edit_image
• get_task_status with the returned batch_id

Parameters:

• model required, from list_models
• image required, a single image URL
• prompt required, trimmed length must be 1 to 2000
• size optional
• resolution optional
• quality optional
• output_format optional
• custom_resolution optional
• count optional, default 1

For Qwen Image Edit (model_id 76), the MCP server sends quality: "medium", resolution: "1024x1024", and customResolution: 1 by default for pricing compatibility.

generate_video

Create an async Open RPC video generation batch.

Recommended flow:

• list_models with type: "video"
• get_model_help
• generate_video
• get_task_status with the returned batch_id

Parameters:

• model required, from list_models
• prompt required, trimmed length must be 1 to 2000
• generation_type optional, default text; supported values are text, image, transition, and reference
• images required for non-text modes: exactly one for image, exactly two for transition, at least one for reference; entries may be image URLs or local image paths
• duration required when the selected model declares supported durations
• resolution required when the selected model declares supported resolutions
• aspect_ratio optional, validated when the selected model declares supported ratios
• style optional, only accepted for models that declare styles
• generate_audio optional, only accepted for models that support generated audio
• multi_clip optional, only accepted for models that support multi-clip generation
• watermark optional, default false; Open RPC video requests send watermark: 0 unless set

Video model constraints are validated locally before a request is sent. Local images used for video generation must be at least 300x300 and are uploaded automatically. wan-v2.6-video is not exposed until its downstream reference image mapping is fixed; kling-o3-pro currently exposes text, image, and transition, but not reference.

get_task_status

Poll a Freebeat async task or Open RPC batch until it reaches a terminal status. Current MCP endpoints return lowercase status values such as pending, completed, and failed; older backends may still return uppercase variants.

For legacy MV/effect tasks, continue polling while the status is still in progress. Only call get_task_result after the status is completed.

For Open RPC image/video batches, pass the returned batch_id as task_id. You can also pass serial_no to query a single batch item. Completed batch items include result URLs directly in get_task_status, so get_task_result is not used for Open RPC batches.

Returns a stable task envelope including:

• task_id
• task_type
• status
• error_message optional, present when backend reports a failed task
• error_code optional, present when backend reports a failed task
• message optional, present when status is completed or failed
• items optional, present for Open RPC batches and containing image_url, video_url, or edit_images when available

get_task_result

Retrieve the output for a completed task. Only call this after get_task_status returns completed. The response uses a stable envelope with task_id, task_type, status, and result.

If the task is not completed yet, this tool returns error code TASK_NOT_COMPLETED.

If the task has failed, this tool surfaces the backend failure as an error.

For current supported completed MV tasks, result is an object containing:

• video_url
• cover_url

Completed effect generation results use the same result object fields:

• video_url
• cover_url