Skip to Content
MCP Documentation

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

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

Environment Variables

VariableRequiredDescription
FREEBEAT_API_KEYYesAPI 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

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:

  • video_url
  • cover_url
Last updated on