MCP Documentation

Copy page

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, 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
• 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

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.

• 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

• task_id

• task_type currently music_video_generation

• status

get_task_status

Poll a Freebeat async task 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.

Continue polling while the status is still in progress. Only call get_task_result after the status is completed.

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

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:

Last updated on May 22, 2026