Suno MCP Integration Guide

MCP (Model Context Protocol) is a model context protocol launched by Anthropic, allowing AI models (such as Claude, GPT, etc.) to call external tools through standardized interfaces. Through the Suno MCP Server provided by WorldAi, you can directly generate music, lyrics, and manage audio projects in AI clients such as Claude Desktop, VS Code, and Cursor.

Feature Overview

Suno MCP Server provides the following core features:

  • Music Generation — Generate AI music through text prompts
  • Custom Creation — Fully control lyrics, titles, and music styles
  • Song Extension — Continue extending existing songs from any point in time
  • Cover/Remix — Create cover versions in different styles
  • Lyrics Generation — Generate structured lyrics based on descriptions
  • Vocal Personas — Save and reuse voice styles
  • Media Conversion — Obtain MP4, WAV, MIDI, vocal separation, and more
  • Style Optimization — Optimize music style tags
  • Task Queries — Monitor generation progress and obtain results

Prerequisites

Before use, you need to obtain an WorldAi API Token:

  1. Register or log in to the WorldAi Platform
  2. Go to the Suno Audios API page
  3. Click "Acquire" to obtain an API Token (free credits are provided for the first application)

Method 1: Use the Hosted MCP Server (Recommended, Zero Installation)

WorldAi has already hosted the Suno MCP Server in the cloud. No local dependencies need to be installed; simply enter the URL below in your AI client to use it:

https://suno.mcp.acedata.cloud/mcp

Authentication method: add Authorization: Bearer Your API Token to the request header (Claude.ai completes this automatically through OAuth, so there is no need to manually enter the Token).

Claude.ai (Web Version, OAuth Login, Simplest)

  1. Open Claude.ai → Customize in the lower-left corner → Connectors → Add More
  2. Enter the following in the URL field: https://suno.mcp.acedata.cloud/mcp
  3. Complete OAuth authorization login (automatically redirects to the WorldAi login page)
  4. Return to the conversation interface, and the tools will be ready to use

Claude Desktop

Edit the configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

Save and restart Claude Desktop for the changes to take effect.

Claude Code (Terminal Command Line)

claude mcp add suno --transport http https://suno.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer 你的API Token"

VS Code (GitHub Copilot)

Create .vscode/mcp.json in the project root directory:

{
  "servers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in the project root directory:

{
  "mcpServers": {
    "suno": {
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

Other MCP-Supported Clients

Any client that supports the MCP Streamable HTTP protocol (such as Windsurf, Cline, ChatGPT Connectors, Gemini CLI, JetBrains AI Assistant, etc.) can connect by entering the following two items:

  • URL: https://suno.mcp.acedata.cloud/mcp
  • Header: Authorization: Bearer Your API Token

Method 2: Run Locally (pip / uvx Installation)

If you need to run offline, customize code, or deploy to an internal network, you can install the MCP Server locally and start it through stdio.

Installation

Install with pip (recommended):

pip install mcp-suno

Or install from source:

git clone https://github.com/AceDataCloud/SunoMCP.git
cd SunoMCP
pip install -e .

After installation is complete, you can use the mcp-suno command to start the service.

Use in Claude Desktop (Local)

Edit the Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "suno": {
      "command": "mcp-suno",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

If using uvx (no need to install the package in advance):

{
  "mcpServers": {
    "suno": {
      "command": "uvx",
      "args": ["mcp-suno"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

Save the configuration and restart Claude Desktop for the changes to take effect.

Use in VS Code / Cursor (Local)

Create .vscode/mcp.json in the project root directory:

{
  "servers": {
    "suno": {
      "command": "mcp-suno",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

Or use uvx:

{
  "servers": {
    "suno": {
      "command": "uvx",
      "args": ["mcp-suno"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

Available Tools List

Tool Name Description
suno_generate_music Generate music through text prompts
suno_generate_custom_music Generate music with custom lyrics and styles
suno_extend_music Continue a song from a specified timestamp
suno_cover_music Create a cover version
suno_concat_music Concatenate song clips
suno_generate_with_persona Generate music using a specified vocal persona
suno_remaster_music Remaster
suno_stems_music Separate audio tracks (vocals/instrumental)
suno_replace_section Replace a specified section in a song
suno_upload_extend Upload audio and continue it
suno_upload_cover Upload audio and create a cover
suno_mashup_music Mash up multiple songs
suno_generate_lyrics Generate lyrics based on a description
suno_create_persona Create a vocal persona
suno_get_mp4 Get the song MP4 video
suno_get_timing Get the lyrics timeline
suno_extract_vocals Extract vocals
suno_get_wav Get high-quality WAV
suno_get_midi Get the MIDI file
suno_optimize_style Optimize music style tags
suno_mashup_lyrics Mash up lyrics
suno_upload_audio Upload custom audio
suno_add_stem Generate a specified instrument or vocal track for existing audio
suno_extract_stem Extract a specified audio track and return a complementary version
suno_generate_sound Generate one-shot or loop sound effects, with optional BPM and key
suno_adjust_speed Adjust speed, with the option to preserve pitch
suno_generate_with_custom_model Create using a ready custom model, supporting instrumental music and automatic lyrics
suno_manage_project Manage versioned Studio multitrack projects by action
suno_get_task Query the status of a single task
suno_get_tasks_batch Batch query task statuses

Usage Examples

After configuration is complete, you can directly call these functions in the AI client using natural language, for example:

  • "Help me generate a pop song about summer"
  • "Make a jazz-style cover of this song"
  • "Continue this song, starting from the 30-second mark"
  • "Generate Chinese lyrics with the theme of travel"
  • "Separate the vocals from this song"
  • "Help me convert this song to MIDI format"

More Information

Advanced Controls and Studio Projects

suno_generate_music supports variety; suno_generate_custom_music also supports max_mode and audio_weight. max_mode uses a higher API billing tier and is disabled by default; it should be set after the user explicitly chooses enhanced mode. Current prices are subject to the platform service page.

suno_generate_with_custom_model can use instrumental=true to generate instrumental music, or use lyric_prompt to automatically generate lyrics; otherwise, provide lyric. Titles and styles may be omitted, and negative_tags, vocal_gender, weirdness, style_influence, duration, and callback_url can also be passed. Explicit control values of 0 will be retained.

The request.action of suno_manage_project can be create, retrieve, save, upload, add_track, generate_track, replace_section, commit_candidate, remove_track, or render. Inputs differ by action, and project modifications should use the most recently retrieved version_id; when saving, pass the complete state, retaining existing tracks and fields.

Except for retrieve, every call must provide an idempotency_key. Use a new key for new write operations; when a timeout occurs or the acceptance result is uncertain, retain the original key and retry with the exact same request, or query the original task—do not automatically change the key and resend a billable generation request. Source audio intervals use seconds, while project timeline intervals use beats. Generation only creates candidates; you need to select a candidate and call commit_candidate before it will be written to a track.

Use suno_get_task to query an asynchronously accepted task_id. Continue waiting when finished_at is empty; after reaching a terminal state, check response.success and errors; do not treat successful acceptance as successful generation, commit, or export. suno_get_tasks_batch returns complete JSON task records, retaining custom model objects, project states, candidates, MIDI, and other types of results. For the complete workflow, see the Studio Project Guide.