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.

`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
count optional, default 1

For GPT-Image 2 (model_id 108), the MCP server sends quality: "medium" and resolution: "1024x1024" by default when omitted. 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
resolution optional
quality optional
count optional, default 1

`generate_video`

Create an async Open RPC text-to-video 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
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
generate_audio optional, only accepted for models that support generated audio

Video model constraints are validated locally before a request is sent.

`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