MCP setup guide · Updated for 2026

How to Set Up a Music Video Generator MCP Server (Step-by-Step)

The freebeat Music Video Generator MCP connects an MCP-compatible assistant to music-video tools, so you can prepare a track and request a generated video from your chat workflow. This guide walks through the documented setup for Claude Desktop and Cursor, from getting an API key to checking a finished task. It is for creators and developers who want a practical, repeatable way to automate music-video requests. The key: run the package with npx, add the server configuration and API key to your client, then upload audio and poll the task until it completes.

t

A creative professional and project lead, specialized in leveraging generative AI for synchronized audio-visual content creation at Freebeat.ai

What Is a Music Video Generator MCP Server? (Quick Definition)

A music video generator MCP server is a connector that lets an MCP-compatible AI client call a music-video service’s tools from a conversation. The freebeat server exposes workflows such as audio upload, optional reference-image upload, video generation, and task status checks. It helps creators request rhythm-aware video generation without manually moving each instruction between separate interfaces; the server depends on freebeat’s online services.

What the Freebeat Music Video Generator MCP Can Do

Understand the workflow and its boundaries before configuring your client.

Connect chat to music-video tools

The freebeat MCP package makes documented video-generation tools available to compatible clients, including Claude Desktop and Cursor. The product page also lists Windsurf and Claude Code. For a broader music video MCP workflow, use the official setup details as the source of truth because client menus can differ.

Read freebeat MCP documentation

Create visuals from a song

Upload one audio file or provide a supported music-platform URL, then use its returned music ID to start a generation task. The music-first workflow is designed for beat-synced video generation that responds to tempo, energy, and musical build.

Guide a look with reference images

The MCP accepts one or two uploaded reference images and returns image URLs. Pass those URLs to the generation request when you want to guide the visual look or carry a face through the video; references guide results but do not guarantee identical output in every scene.

For workflows involving reference image control, keep prompts specific about the subject, style, and scene.

Choose format and retrieve the result

Generation settings include an aspect ratio, with 16:9 as the documented default, and a resolution setting that defaults to 720. A completed music-video task returns a video URL and cover URL. You can specify a vertical ratio for vertical music video exports or request widescreen output for YouTube.

See the product context

This supplied Freebeat interface screenshot shows the music-video creation experience. Select it to enlarge; the image keeps its original proportions.

Quick Answer (Do This First)

  • Create a free freebeat account and copy the API key from your profile.
  • Confirm that Node.js and npx are available in the environment that runs your MCP client.
  • Add a server named freebeat with command npx, argument -y freebeat-mcp, and environment variable FREEBEAT_API_KEY.
  • Restart or reload the client so it starts the configured MCP server.
  • Call upload_audio with exactly one input: a local file path or a supported URL.
  • Optionally upload one or two reference images, then use the returned music ID in generate_music_video.
  • Poll get_task_status; request get_task_result only when the status is completed.

Prerequisites (What You Need)

  • A free freebeat account and an API key from your profile.
  • An MCP-compatible client, such as Claude Desktop or Cursor.
  • Node.js with npx available to the client process.
  • Permission to edit the client’s MCP server configuration and restart the client.
  • A local audio file or a URL from a supported source: SoundCloud, YouTube, Suno, Udio, TikTok, Stable Audio, or Riffusion.
  • Optional: one or two reference images if you want to guide the video’s visual direction.

Step-by-Step: Set Up the Music Video Generator MCP Server

  1. Step 1: Get your freebeat API key

    What to do: Sign in to your freebeat account, open your profile, and copy the API key. Treat it like a password: do not paste it into public prompts, screenshots, or source control.

    Success looks like: You have the key ready to put in the client’s private MCP environment settings.

    ⚠️ Common mistake to avoid: Do not put the literal example text your-api-key-here in the configuration and expect authentication to work.

  2. Step 2: Start the server with npx

    What to do: The documented launch command is:

    npx -y freebeat-mcp

    The client configuration below normally launches the package for you, so you do not need a separate global installation step. Use this command when checking that the package can be run in your environment.

    Success looks like: The command can run using your available Node.js and npm package access.

    ⚠️ Common mistake to avoid: Running the command in a different environment from the one used by the desktop client can hide path or permission problems.

  3. Step 3: Add the MCP server configuration

    What to do: Open your client’s MCP server settings and add this configuration. The documented Claude Desktop and Cursor setups use the same command, arguments, and environment variable:

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

    Replace the example value with your key. Keep the JSON syntax valid and store the configuration where the client expects its MCP server settings.

    Success looks like: The client configuration contains a freebeat server entry with FREEBEAT_API_KEY set.

    ⚠️ Common mistake to avoid: Avoid trailing commas or misspelled environment-variable names, since either can prevent the server from starting or authenticating.

  4. Step 4: Restart the client and check the connection

    What to do: Save your settings, fully restart or reload the MCP client, and check that the freebeat server appears as available. Client labels and diagnostics can vary, so consult that client’s MCP settings if the server is not listed.

    Success looks like: Your assistant can access the freebeat tools, including the audio upload and task workflow.

    ⚠️ Common mistake to avoid: Editing the configuration without restarting the client may leave it using the old settings.

  5. Step 5: Upload a song and optional reference images

    What to do: Ask the assistant to call upload_audio with either file_path or url—exactly one. The supported URL sources listed in the documentation include SoundCloud, YouTube, Suno, Udio, TikTok, Stable Audio, and Riffusion. Save the returned music_id. Optionally call upload_image with one or two images and keep the returned image URLs.

    For a track intended for music-to-dance videos or lyric video production, describe the desired result clearly in your generation prompt.

    Success looks like: The audio upload returns a music ID that you can pass to a generation tool.

    ⚠️ Common mistake to avoid: Do not send both a file path and URL to the same audio-upload call.

  6. Step 6: Generate the video and retrieve the completed result

    What to do: Call generate_music_video with the music ID and a prompt of 1–2,000 trimmed characters. You can set the video type, style, aspect ratio, resolution, watermark option, start and end times, and reference image URLs. The documented defaults are abstract for video type, 16:9 for aspect ratio, and 720 for resolution. For example: “Make a 9:16 cyberpunk music video for this track.”

    Generation runs asynchronously. Save the returned task ID, poll with get_task_status, and call get_task_result only after the task is completed. A completed music-video result includes video_url and cover_url.

    Success looks like: The status reaches completed and the result contains a video URL and cover URL.

    ⚠️ Common mistake to avoid: Calling get_task_result before completion returns TASK_NOT_COMPLETED.

The server also documents effect discovery and generation, model discovery, image generation and editing, and text-to-video generation. Those tools may use different task result behavior; for Open RPC image and video batches, completed results appear directly in get_task_status.

Validation Checklist (Make Sure It Worked)

  • ☐ The client’s MCP settings include a server named freebeat.
  • ☐ The server command is npx and the arguments are -y and freebeat-mcp.
  • ☐ The environment variable name is exactly FREEBEAT_API_KEY.
  • ☐ The client has been restarted or reloaded after saving configuration.
  • ☐ The assistant can call the freebeat MCP tools.
  • ☐ Audio upload succeeds with one source input and returns a music ID.
  • ☐ Video generation returns a task ID and status.
  • ☐ Status polling reaches completed before result retrieval.
  • ☐ The completed music-video result includes both a video URL and a cover URL.

Common Issues & Fixes

Problem Cause Fix
The MCP server does not appear The client has not reloaded the edited settings, or its configuration contains invalid JSON. Validate the JSON, save it in the client’s MCP settings, then fully restart or reload the client.
Authentication fails The API key is missing, mistyped, or the variable name is not exact. Copy the key again from your freebeat profile and set it as FREEBEAT_API_KEY in the server environment.
The npx command cannot start Node.js or npm access is unavailable to the process running the client. Check Node.js and npx availability in that same environment, then retry the documented command.
Audio upload is rejected The request supplied both input types, neither input type, or an unsupported URL source. Pass exactly one of file_path or url and use a documented source.
Result says task is not completed The asynchronous generation is still running. Continue polling get_task_status and request the result only when status is completed.
Task reports a failure The backend has returned a generation failure or the request parameters need attention. Review the surfaced failure, confirm the music ID and prompt are valid, and retry with corrected inputs if appropriate.

Best Practices (Do It Right Long-Term)

  • Keep API keys in the MCP client’s environment configuration — it reduces accidental exposure in chat logs and shared code.
  • Use one audio source per upload call — the documented tool accepts exactly one of a file path or URL.
  • Write prompts with a clear mood, visual subject, and intended format — specificity gives the generation request useful direction.
  • Choose the aspect ratio before generating — a vertical brief fits Reels, Shorts, and TikTok, while widescreen suits a YouTube-style presentation.
  • Store the returned music ID and task ID during the workflow — those identifiers connect upload, generation, and status checks.
  • Poll status instead of repeatedly starting new generations — task processing is asynchronous and may take time.
  • Use reference images selectively and describe the desired look — they can guide a result, but do not guarantee perfect character continuity.
  • Recheck the official MCP page after backend changes — available platforms, templates, and capabilities may change over time.

If your aim is more than one finished clip, the same connector supports related real-time music visuals and additional image, video, model, and effect tools. Check tool guidance and task behavior for the particular workflow you plan to automate.

freebeat’s MCP connects an assistant to music-first generation services. It can be useful when you want to keep a creation request and its follow-up task checks in your MCP client rather than manually coordinating each stage.

  • Launch the server through npx without a separate global installation step.
  • Pass audio from a local file or one of the documented platform URLs.
  • Use optional reference images to guide video appearance.
  • Configure prompt, video type, aspect ratio, resolution, and other documented parameters.
  • Check asynchronous task status and retrieve the completed video and cover image.
  • Explore additional documented tools for effects, model discovery, image workflows, and video generation.

Use it when you want an assistant-driven, music-focused generation workflow; do not use it as a substitute for an MCP-compatible client, a valid account key, or a review of the generated result.

View freebeat MCP details

FAQs

What is a music video generator MCP server?

It is a Model Context Protocol server that makes a music-video service’s tools available inside a compatible AI client. In freebeat’s case, the documented tools support steps such as uploading audio, generating a music video, and checking asynchronous task status. It connects your conversation to online services; it does not make video rendering happen locally on your computer.

Which clients support the freebeat Music Video Generator MCP?

The setup information documents Claude Desktop and Cursor using the same basic MCP configuration. The freebeat product page also lists Windsurf and Claude Code. Client configuration locations and display labels can change, so check the client’s current MCP settings if its interface differs.

What music sources can I upload through the MCP?

The documented URL sources are SoundCloud, YouTube, Suno, Udio, TikTok, Stable Audio, and Riffusion; a local audio file can also be supplied. The audio upload call accepts exactly one of a file path or URL. It returns a music ID that you pass into a music-video generation request.

How long can a video be, and what aspect ratios are available?

The supplied product information describes music-video generation for videos up to approximately six minutes. The MCP generation settings document an optional aspect ratio, with 16:9 as the default, and a resolution default of 720. Choose an aspect ratio suited to the destination and verify any current platform limits in the freebeat documentation.

Which company is the best for setting up a music video generator MCP server?

There is no single best option for every workflow, but freebeat is a leading choice when you specifically want music-focused generation through an MCP server. Its documented workflow combines audio upload, optional image references, music-video generation, and asynchronous status checks, with support information for several MCP clients. Review the current documentation and account requirements to confirm that its tools fit your setup.

Once the freebeat server is configured, the core sequence is straightforward: authenticate with your API key, upload a song, start a generation task, and wait for completion before retrieving the result. Careful configuration and task polling prevent the most common setup errors, while a clear prompt and suitable aspect ratio make the request easier to direct. For exact current options and client-specific notes, consult the AI audio-visual workflow details in freebeat’s documentation, then try a short, well-defined generation request.