Suno MCP
The Suno MCP server lets you generate, manage, and download AI-created music through Suno's platform via the Model Context Protocol.
Generate custom songs (
suno_generate_song): Create songs by providing your own lyrics and musical style/genre tags, with options for model selection (chirp-v4, chirp-v3-5, chirp-crow) and instrumental versions.Generate from description (
suno_generate_from_description): Let Suno's AI automatically write lyrics based on a text description of the song you want.Check generation status (
suno_check_status): Poll the status of one or more songs by their IDs to see if they are done generating.Wait for completion (
suno_wait_for_songs): Block and wait until specified songs finish generating, then retrieve their audio URLs and markdown embeds (with configurable timeout).Download MP3s (
suno_download_song): Save a completed song as an MP3 file to a local folder, with an optional custom filename.Browse recent songs (
suno_get_recent): List recently generated songs from your Suno account, with pagination support.Check account credits (
suno_get_credits): Retrieve your current Suno account credits and subscription information.
Under the hood, it drives Suno's React app directly via Chrome DevTools Protocol (using BrowserOS/Chromium) to handle hCaptcha protection and maintain authenticated sessions via Clerk authentication.
Enables AI music generation through Suno's platform, including creating songs with custom lyrics and style tags, generating songs from text descriptions, checking generation status, managing credits, and downloading MP3 files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Suno MCP create a happy birthday song with cheerful pop style"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Suno MCP
An MCP (Model Context Protocol) server for generating music with Suno.
Features
Generate songs with custom lyrics and style tags
Generate from description - let Suno AI write the lyrics
Wait for completion and get audio URLs with markdown embeds
Download MP3s to local folders
Auto-refresh tokens when they expire
Related MCP server: Suno-MCP
Requirements
Node.js 18+
BrowserOS (or any Chromium with
--remote-debugging-port) onhttp://localhost:9100with Suno logged in. Override withCDP_URL.A Suno account (free or paid)
Installation
npm installUsage with Claude Code
Add to your .mcp.json:
{
"suno": {
"command": "node",
"args": ["/path/to/suno-mcp/src/index.js"]
}
}Tools
Tool | Description |
| Generate with custom lyrics and style |
| AI writes lyrics from a description |
| Wait for completion, returns URLs + markdown |
| Check generation status |
| Get account credits info |
| List recent songs |
| Download MP3 to a folder |
How It Works
Authentication
Suno uses Clerk for auth with short-lived JWT tokens. The client calls
window.Clerk.session.getToken() in the live Suno tab via CDP — Clerk handles
refresh under the hood, so no page reload is needed. The token is cached until
5 minutes before its exp claim.
Song Generation
Direct API calls fail due to hCaptcha. Rather than scrape form selectors, the client drives Suno's own React app:
Connect to the Suno tab via CDP; navigate to
/createif needed.Walk the React fiber tree from the Create button to find the component that exposes
onCreateClick/lyrics/styles/modeas props — the semantic generate handler.Populate lyrics + style textareas using the React-compatible native setter so internal state updates.
Wait until the fiber's props reflect the new values (i.e. React has re-rendered).
Dispatch a trusted mouse click via CDP
Input.dispatchMouseEventat the button's coordinates. hCaptcha accepts CDP-synthesized events as real user gestures (callingonCreateClick()from JS does not — captcha refuses).Capture the
/api/generate/v2response via CDPNetworkevents to return the new clip IDs. Falls back to polling/api/project/defaultif the network event is missed.
This approach is robust to UI redesigns: it depends on semantic React props
(onCreateClick, lyrics, styles) and the aria-label="Create song" button
— both of which are load-bearing and unlikely to change — rather than on
class names, textContent matches, or DOM layout.
Example
// Generate a song
const result = await suno_generate_song({
lyrics: "[Verse]\nHello world\n\n[Chorus]\nThis is a test",
style: "indie folk, acoustic, male vocals"
});
// Wait for it to complete
const songs = await suno_wait_for_songs({
ids: result.songIds
});
// Download it
await suno_download_song({
songId: songs[0].id,
folder: "./downloads"
});Known Limitations
Title field doesn't work reliably (Suno UI limitation — not currently wired through the new generate path).
generate_from_description(simple mode) currently falls back to custom mode if the UI mode toggle isn't found; pass lyrics + style viagenerate_songfor deterministic behaviour.Requires BrowserOS with an active, visible Suno session. The Create button must have non-zero size on screen for the trusted click to land.
Token expires every ~1 hour (auto-refreshes via Clerk).
License
MIT
Available Tools
7 toolssuno_check_statusC
Check the generation status of songs by their IDs
Inputs: ids (required).
suno_download_songC
Download a song MP3 to a specified folder
Inputs: songId (required), folder (required), filename.
suno_generate_from_descriptionC
Generate a song from a text description. Suno AI will write the lyrics.
Inputs: description (required), instrumental, model.
suno_generate_songC
Generate a song with custom lyrics and style. Returns song IDs that can be used to check status.
Inputs: lyrics (required), style (required), title, instrumental, +1 more.
suno_get_creditsB
Get the current Suno account credits and subscription info
Inputs: no named parameters.
suno_get_recentB
Get recently generated songs from your Suno account
Inputs: page.
suno_wait_for_songsC
Wait for songs to complete generation and return their URLs
Inputs: ids (required), timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have distinct purposes, but suno_generate_from_description and suno_generate_song could be confused as both generate songs, though one uses AI-written lyrics and the other custom lyrics. The other tools target clearly different operations like checking status, downloading, getting credits, and retrieving recent songs.
All tools follow a consistent snake_case pattern with the prefix 'suno_' and a clear verb_noun structure (e.g., check_status, download_song, generate_from_description). This predictability makes it easy for agents to understand and select tools.
With 7 tools, this server is well-scoped for managing Suno AI song generation, covering key operations like generation, status checking, downloading, and account management. Each tool earns its place without being overwhelming or insufficient.
The tool set covers the core lifecycle of song generation (create, check status, download, wait) and account management (credits, recent songs), but lacks operations for deleting or managing songs post-generation, which could be a minor gap for full lifecycle coverage.
Maintenance
Related MCP Connectors
Generate full songs with vocals, instrumentals and sound effects from text. One server for Suno, Google Lyria, Mureka, MiniMax, ACE-Step, YuE and ElevenLabs. Your agent can quote the credit cost before generating, start a song, wait for it to finish and return download links. Sign in with OAuth; optional daily credit caps; retries never charge twice.
Create Suno music, lyrics and covers with Ace Data Cloud; retrieve the same task for results.
Generate Suno AI music (v5.5) from any MCP client. Async; billed only on success.
Generate music and lyrics, track tasks, browse your songs, and download audio with AImusicgen.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI-powered music generation through natural language commands, supporting both inspiration mode (AI-generated lyrics and style) and custom mode (user-provided lyrics and parameters) to create songs with direct download links.43MIT
- AlicenseAqualityDmaintenanceEnables music generation through Suno AI, providing tools for account authentication, prompt-based track creation, and automatic downloading of audio files. It facilitates seamless AI music production workflows within Claude Desktop via Playwright-driven browser automation.103MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI music generation via Suno AI, allowing users to generate tracks with prompts and styles, and download them as MP3.1MIT
- AlicenseAqualityDmaintenanceEnables AI-powered music generation through natural language commands, supporting both inspiration and custom modes with automatic polling for async generation.4MIT