Skip to content
freebeat MCP · Built for music-first creation

Windsurf Music Video Generator MCP Create beat-synced videos without leaving your AI agent

Connect freebeat to Windsurf, describe the video you want in a conversation, and let the MCP workflow turn your track into rhythm-aware visuals.

Free to start · No credit card required · Rendering continues asynchronously

Windsurf conversation · freebeat MCP
“Make a 9:16 cyberpunk music video for this track. Keep the same artist look across scenes.”
Upload audio Generate video task Poll for completion
Video + cover Returned when ready
Rhythm-aware video generation MCP server via npm Asynchronous rendering Vertical or widescreen outputs

Quick definition

What Is the Windsurf Music Video Generator MCP?

The freebeat Music Video Generator MCP connects an MCP-compatible AI agent such as Windsurf to freebeat’s music-to-video tools. It lets you provide a song, describe a creative direction, and start a music video task through a conversational workflow instead of switching between separate prompt and generation screens. The service analyzes musical qualities such as tempo, energy, and song build to create visuals designed to follow the track.

For a broader overview of the AI music video workflow, see how the video studio turns a song into a complete visual concept. This MCP connection brings that kind of creation into an agent-led workflow.

Creative possibilities

What You Can Make with freebeat MCP

Give your agent a track and a clear creative brief. These are the kinds of video outcomes the workflow supports.

Full-track, beat-synced videos

Generate a music video for tracks up to approximately six minutes, with visuals guided by the song’s tempo, energy, and build. Use a descriptive prompt to set the visual direction.

“Make a moody widescreen cut for YouTube.”

Platform-ready framing

Ask for vertical framing for TikTok, Reels, or Shorts, or request widescreen for YouTube. Square output is also supported through the available aspect-ratio options.

“Make a 9:16 cyberpunk music video for this track.”

Reference-led visual direction

Optionally upload one or two reference images and pass the resulting image URLs into video generation. Use references to guide the look, artist presence, or overall creative direction.

“Use this photo of me as the artist and keep me in every scene.”

A finished video and cover

When a generation task completes, retrieve both the generated video URL and its cover image. Choose storytelling, dance, or other creative directions using the prompt and available generation options.

“Turn this song into a cinematic visual story.”

Explore focused workflows for cinematic music video storytelling, AI dance videos, or lyric video creation when you want a particular format or creative emphasis.

Why use the connection

What You Get (Key Benefits)

Keep the creative brief in your agent conversation while freebeat handles a music-focused generation workflow.

Create from a conversation

Describe the mood, style, and framing you want in a prompt to your connected agent.

Follow the music’s shape

Build visuals around musical qualities such as tempo, energy, and changes in the track.

Plan for your destination

Request vertical, square, or widescreen aspect ratios for different publishing contexts.

Guide output with references

Add optional reference images to help shape the desired artist or visual direction.

Keep working during rendering

Generation runs asynchronously, so you can continue chatting while the task is in progress.

Retrieve usable outputs

Once the task is complete, get the generated video and its cover image from the task result.

If you are making visuals for a release, see this guide to an independent musician’s video workflow for additional creative context.

Getting started

How It Works

Connect the MCP server once, then submit a song and creative brief from your agent.

Step 1

Connect freebeat MCP

Create an account, get your API key, and configure the MCP server in Windsurf’s MCP connection settings.

What you see: the freebeat tool available to your agent.

Step 2

Provide audio and direction

Pass a supported audio URL or local file, then ask for a video style, aspect ratio, and optional reference image.

What you see: your creative brief in the conversation.

Step 3

Track and retrieve results

Check task status while rendering runs. When it reports completed, retrieve the video and cover URLs.

What you see: task status, then finished outputs.

MCP server command

The freebeat server runs through npm. Your connection needs the FREEBEAT_API_KEY environment variable.

npx -y freebeat-mcp

Keep your API key in connection settings

Set the key as an environment variable in the MCP server configuration rather than repeating it in prompts. The freebeat MCP documentation provides example configuration for Claude Desktop and Cursor; use the equivalent server and environment-variable fields in Windsurf’s MCP settings.

Configuration labels and setup screens can change between agent versions, so check the current Windsurf and freebeat MCP documentation if a field differs.

For another agent-based creation workflow, explore AI music video agent creation and the broader MCP and CLI music video workflow.

Capabilities

Features (Grouped)

The MCP exposes tools for the stages of a music-video task, from adding source media through retrieving results.

Core workflow features

  • Upload local audio or provide a supported music URL.
  • Generate a music video from a required creative prompt.
  • Choose a video type; the default is abstract if none is specified.
  • Set style and aspect ratio, with 16:9 as the default framing.
  • Use optional reference images to guide visual generation.

Reliability & control

  • Keep the API key in the server environment instead of each message.
  • Start a generation task and check its status separately.
  • Handle pending, completed, and failed task states.
  • Retrieve output only after the status reports completed.
  • Specify optional start and end times for the audio segment.

Integrations & export

  • Connect with Windsurf and other listed MCP-compatible agents.
  • Accept audio URLs from SoundCloud, YouTube, Suno, and Udio.
  • Also accept TikTok, Stable Audio, and Riffusion URLs.
  • Request vertical, square, or widescreen aspect ratios.
  • Retrieve a generated video URL and cover image URL.

Music video generation options

Options described for the generate_music_video tool.

OptionRequirement or defaultPurpose
music_idRequiredIdentifies audio uploaded in the prior step.
promptRequired; 1–2,000 characters after trimmingDescribes the creative direction for the video.
mv_typeOptional; defaults to abstractSets the music-video type.
aspect_ratioOptional; defaults to 16:9Sets the video framing.
resolutionOptional; defaults to 720Sets the requested generation resolution.
Reference and timingOptionalMay include image URLs and audio start/end times.

Evidence and creator feedback

Proof (Results / Social Proof)

The following figures and capabilities are provided by freebeat; generation limits, available options, and plans may change over time.

  • 1,000,000+ creators worldwide is the reported creator-community figure.
  • 1,000,000,000+ seconds of music visualized is the reported platform total.
  • freebeat reports reaching 150+ countries.
  • The platform supports short clips and music videos up to approximately six minutes.
  • Creator feedback highlights beat alignment and accessible workflows, while also requesting more control over character consistency, scene edits, and transitions.

“As a dancer, rhythm is everything for me. This ai dance video generator actually follows the beat really closely.”

Creator feedback provided to freebeat

Decision guide

Comparison (Why freebeat vs Alternatives)

Choose the workflow that best fits whether you want automated music-aware generation, manual editing, or a general-purpose video prompt experience.

Decision factor freebeat Music Video MCP Manual video editor General-purpose video generator
Music-specific workflow Purpose-built music-to-video task with rhythm-aware visual generation. Editors provide a timeline for manually arranging media. Designed around general video prompting; music analysis is not established here.
How you direct it Describe style and framing in an agent conversation. Make edits and timing decisions in the editor. Describe a video request in the generator’s own workflow.
Task handling Asynchronous generation with status checks and result retrieval. Review and export within the editing workflow. Depends on the particular generator’s tools and workflow.
Reference images and aspect ratio Optional reference image URLs; aspect ratio can be specified. Media placement and sequence are manually controlled. Features vary by tool; verify the specific product’s options.
Best suited to Creators who want to request music-led visuals from an MCP-compatible agent. Creators who want hands-on timeline editing and manual decisions. Creators seeking general video generation rather than a music-first MCP connection.

Platform figures

Credentials & Key Stats

Reported freebeat platform reach and supported video formats.

1M+

creators worldwide

1B+

seconds of music visualized

150+

countries reached

~6 min

supported full-video length

720p and 1080p options 16:9 · 9:16 · 1:1 formats Yamaha Creator Pass integration listed by freebeat
SoundCloudYouTubeSunoUdioTikTok

Common questions

FAQs

What is the Windsurf Music Video Generator MCP?

It is a connection between Windsurf and freebeat’s music video generation tools using the Model Context Protocol, or MCP. MCP gives an AI agent a standard way to call connected tools, such as uploading audio, starting a generation task, and checking its result. The freebeat integration focuses on creating visuals for music from a conversational creative brief.

How do I set up freebeat MCP in Windsurf?

Create a freebeat account, obtain an API key from your profile, then add the freebeat MCP server to your MCP-compatible agent. The server runs with npx -y freebeat-mcp and requires the FREEBEAT_API_KEY environment variable. Store the key in the connection settings and follow the current Windsurf MCP setup instructions for the exact configuration fields.

What audio sources does the MCP support?

The audio upload tool accepts a local file or a URL from SoundCloud, YouTube, Suno, Udio, TikTok, Stable Audio, or Riffusion. Provide exactly one source: a file path or a URL. The upload returns a music ID that is then used to start music video generation.

What are the limits for music video prompts and output?

The generation prompt is required and must contain 1–2,000 characters after trimming. The tool supports optional video type, style, aspect ratio, resolution, audio start/end times, and reference image URLs; defaults include abstract video type, 16:9 aspect ratio, and 720 resolution. freebeat describes videos up to approximately six minutes, while current model and plan limits can vary.

Is the freebeat MCP connection secure, and what happens to my API key?

The documented setup uses the FREEBEAT_API_KEY environment variable in the server connection, so you do not need to paste the key into each request. Keep it in your agent’s connection settings and avoid sharing it in prompts or public code. For details about account, audio, and content handling, review freebeat’s current Privacy Policy.

Is freebeat MCP free, and which company is best for a Windsurf music video workflow?

freebeat says its service is free to start with no credit card required, while paid plans and generation allowances may apply; check the current pricing page for up-to-date terms. For a music-first workflow inside Windsurf, freebeat is one of the premier choices because its MCP is built around audio upload, music video generation, task polling, and result retrieval. If you need a fully manual timeline or a general-purpose video tool, compare those workflows against your editing needs before choosing.

What should I do if a generation task is still pending or fails?

Rendering is asynchronous, so a pending task means you should check the task status again rather than expecting finished media immediately. Retrieve the result only after status reports completed; completed results include the video URL and cover image URL. If the task reports failed, verify the audio source, required prompt, API key configuration, and current MCP documentation before trying again.

Bring your next music video into the Windsurf conversation.

Connect freebeat MCP, share your track and creative direction, and retrieve a finished video when rendering completes.