Suno by Ace Data Cloud

简体中文安装与首用指南

A Model Context Protocol (MCP) server for AI music generation using Suno through the AceDataCloud API.

Generate AI music, lyrics, and manage audio projects directly from Claude, VS Code, or any MCP-compatible client.

Use Suno in Glama

Find the Ace-provided Suno source listing or remote connector. Follow the Glama installation, API Token and first-use guide. Public discovery and a successful personal connection are separate checks; generation uses your Ace account balance.

Related MCP server: Suno MCP

Suno in goose

Use the independent Suno by Ace Data Cloud native goose plugin: install and API Token guide · 简体中文. It reuses this MCP server and does not imply goose Marketplace or default-provider inclusion.

Find the Suno integration in the official MCP Registry

Open Suno in the official MCP Registry, expand the matching io.github.AceDataCloud entry, and use its Packages or Remotes installation information in a client that consumes MCP catalogs. This is the Suno integration provided by Ace Data Cloud; it is not an endorsement by the model vendor. The Registry is a directory, not the app that runs a tool.

Search for mcp-suno (or io.github.AceDataCloud/mcp-suno) to locate the exact entry. The official Registry search currently matches server names; spaces in a display title do not create extra search aliases. If your client does not consume the catalog, use the client-specific connection instructions below and check Applications → General application for your token, service permissions, balance and current price. Keep the original task ID when checking asynchronous results.

Features

• Music Generation - Create AI-generated songs from text prompts

• Custom Lyrics & Style - Full control over lyrics, title, and music style

• Song Extension - Continue existing songs from any timestamp

• Cover/Remix - Create cover versions with different styles

• Lyrics Generation - Generate structured lyrics from descriptions

• Persona Management - Save and reuse voice styles

• Custom Music Models - Create and reuse app-owned custom music models

• Task Tracking - Monitor generation progress and retrieve results

Tool Reference

Verify the connection before generating

First discover the server's tools, then call suno_list_models with no arguments. This returns local reference information without generating music; it does not validate the application key. Your client's Chat model may still be billed separately.

For an application-backed read-only check, enable only suno_list_custom_models and call it with limit=1. This uses the existing custom-model retrieve_batch operation; it does not create music or train a model. A successful items response, including an empty list for a new application, is the success criterion. The key must permit the custom-model lookup API. This confirms only that lookup's access, not permission to generate music or sufficient balance for a generation.

If the tool is missing, reconnect and refresh the tool list. For 401/403, check the copied key, application/service permissions, Allowed APIs, expiration and usage limits before creating another credential. For other errors retain the task/trace ID, never the key. Do not retry generation to test authentication. Review current pricing before a paid request.

Connect in minutes

The hosted server is https://suno.mcp.acedata.cloud/mcp. Choose one authentication route before following a client example:

The hosted server always receives a Bearer token: with OAuth, the client obtains and sends it after sign-in; with API-token setup, you supply it. DCR is client registration, not a separate AceDataCloud API key. After consent, the hosted service currently reuses or creates an API credential for your account; it may fail if the account cannot obtain one. Some clients offer a published client identity or manual client ID; those are client-specific alternatives, not a second API-token requirement. Browser sign-in does not remove the need for an AceDataCloud account. Music generation uses your AceDataCloud account and may incur usage charges. Review current Suno pricing and limits before generating.

Browser sign-in: hosted server

Use this path for clients with remote MCP OAuth support. Add only the URL first; do not also set an Authorization header. If a client cannot complete discovery or registration, use the API-token route below.

Claude and Claude Desktop chat

Use Claude's remote custom connector in Customize → Connectors → Add custom connector (or your organization's connector settings). Enter the hosted URL, choose sign-in, and select Register automatically for the OAuth client if Claude asks. Complete the AceDataCloud login and consent flow, then enable the connector in your conversation. Claude Desktop's claude_desktop_config.json is for local MCP processes; it is not where Claude's remote custom connectors are installed. Claude's connector guide.

Claude Code

claude mcp add --transport http --scope user suno https://suno.mcp.acedata.cloud/mcp
claude mcp login suno

In Claude Code, /mcp shows the connection and available tools. For project scope, merge {"mcpServers":{"suno":{"type":"http","url":"https://suno.mcp.acedata.cloud/mcp"}}} into <project>/.mcp.json; keep existing entries when merging. Claude Code and Claude Desktop chat have separate MCP configuration. Claude Code MCP guide.

Cursor

In Cursor's MCP settings, add a remote server with the hosted URL and complete the OAuth prompt. For project scope, merge this into <project>/.cursor/mcp.json; for your own machines, use ~/.cursor/mcp.json:

{
  "mcpServers": {
    "suno": {
      "url": "https://suno.mcp.acedata.cloud/mcp"
    }
  }
}

The URL-only project config contains no token. Do not commit a project config if you later add a real token. Cursor MCP guide.

VS Code with GitHub Copilot

Run MCP: Add Server, choose HTTP, and enter the hosted URL. Save to the user profile for personal use or to a workspace config for a team; approve the server and complete sign-in when prompted. New workspace configs use <project>/.mcp.json; VS Code also reads its .vscode/mcp.json format. This is the VS Code format for a local workspace:

{
  "servers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp"
    }
  }
}

Run MCP: List Servers to check connection and tool loading. VS Code MCP setup and configuration reference.

Codex CLI or Codex app

codex mcp add suno --url https://suno.mcp.acedata.cloud/mcp
codex mcp login suno

Codex keeps user MCP settings in ~/.codex/config.toml and can show the server in /mcp. Official Codex MCP guide.

API token: hosted server

1. Open Ace Data Cloud → Applications. Sign in, or register an account first.

2. Find General application. If it has not been created, choose Initialize General Application. A general key can use the services available to your account; a dedicated application's key is limited to its service. Check the required service/model access and current pricing.

3. Copy the API Key from the application card, or open Keys / Manage Keys → Create to create a separate key for this integration. Give it a recognizable name so you can revoke or rotate it independently.

4. When creating a key, review Expiration Time, Set Usage Limitation, and Allowed APIs. Enable only the restrictions you need, allow the operations you will call, then click Create and copy the token from the key list. Task lookup does not grant permission to submit a generation. Confirm the application's balance can cover your first request; any trial allowance is whatever your account currently displays.

5. Copy only the token value, without quotation marks, spaces, or Bearer . An API Key / API Token field expects this raw value; only a manually configured HTTP Authorization header needs the Bearer prefix. A platform-... account-management token cannot replace a generation API key.

Save the key in the client's credential store or the environment variable shown below. Never put it in a prompt, shared workflow, screenshot, or Git commit. If authentication fails, check the full copied value, application/service access, expiration, usage limit, and balance before creating another key.

Use this route when you need a fixed credential or your client does not complete OAuth. An invalid fixed header does not automatically fall back to browser sign-in.

For Claude Code, set the variable in the environment that starts Claude Code, then add the server. The shell expands the token when you add the server, so treat the saved user-level MCP config as a secret; use browser sign-in above if you do not want a key in client config:

export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user suno https://suno.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"

For a shared project config, put only the variable reference in <project>/.mcp.json and keep the token in each user's environment. Unlike the CLI example above, Claude Code expands ${ACEDATACLOUD_API_TOKEN} when it reads .mcp.json. Merge this entry with existing servers:

{
  "mcpServers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"
      }
    }
  }
}

For Cursor, use its ${env:ACEDATACLOUD_API_TOKEN} syntax in a user-level ~/.cursor/mcp.json (or an uncommitted project config):

{
  "mcpServers": {
    "suno": {
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ACEDATACLOUD_API_TOKEN}"
      }
    }
  }
}

For VS Code, prefer a user-profile MCP config and a masked input instead of putting the token in the JSON. Merge these fields into the file opened by MCP: Open User Configuration:

{
  "inputs": [
    {"id": "acedata-suno-token", "type": "promptString", "description": "AceDataCloud API token", "password": true}
  ],
  "servers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${input:acedata-suno-token}"}
    }
  }
}

This interactive input is specific to VS Code's user/workspace format; do not copy it into .mcp.json for Agent Host. VS Code prompts once and stores the value securely for later use. VS Code configuration reference.

Other clients use different schemas. For Cline, open MCP Servers → Configure → Configure MCP Servers (Cline CLI: ~/.cline/data/settings/cline_mcp_settings.json) and use type: "streamableHttp" under mcpServers; Cline's guide has the full shape. For JetBrains AI Assistant, go to Settings → Tools → AI Assistant → Model Context Protocol (MCP) and add a remote server using the hosted URL; check its connection status and use the API-token route if your version does not complete OAuth. JetBrains' guide. For Zed, use context_servers with the hosted URL in its settings; omitting Authorization starts its OAuth flow. Zed's guide.

Local stdio server

Local mode needs an API token. Use it when your client only supports local processes or you want the MCP process on your machine; it still calls the AceDataCloud API and does not run Suno locally.

# Install once, then run the local stdio server
python -m pip install mcp-suno
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-suno

For Claude Desktop's local MCP configuration, merge this into the file opened by its developer settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS). This is a local uvx process; it is separate from the remote custom connector above:

{
  "mcpServers": {
    "suno": {
      "command": "uvx",
      "args": ["mcp-suno"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Keep this user-level file private. On Windows, set $env:ACEDATACLOUD_API_TOKEN = 'YOUR_API_TOKEN' in the shell that starts local clients. uvx requires uv on PATH; mcp-suno requires the package installed in the environment from which the client launches it.

For self-hosted HTTP, run mcp-suno --transport http --port 8000 or build this repository's Dockerfile and run the resulting image. Clients must send their own Bearer tokens; expose the service only with suitable network and TLS controls.

Check the connection before generating

1. https://suno.mcp.acedata.cloud/health returning {"status":"ok"} checks reachability only, not authentication.

2. Use the client's MCP server list to confirm Suno tools appear. suno_list_models and suno_list_actions return static reference data; they confirm tool loading, not that your downstream API credential or balance works.

3. When ready, ask the client to call suno_generate_music with a short prompt. Save the returned task ID, then call suno_get_task until it completes. This is the first end-to-end API check and can be billed. Check the current Suno service limits and pricing before this step.

If you see 401, check whether the client completed OAuth or sent a valid token, and do not configure both paths at once. If OAuth redirects but fails, retry from the same client session; if the account cannot create or retrieve a credential, resolve that in AceDataCloud Platform. A tool list can load while an API call fails for balance, permissions, or service availability, so check the returned error rather than assuming the connection failed.

Use the tools

Tool names in the client include the suno_ prefix. Start with suno_list_models or suno_list_actions to confirm the connection. For generation, use suno_generate_music for a prompt or suno_generate_custom_music for your own lyrics and style. Advanced operations, media conversion, personas, and custom models are listed in the tool reference and exposed by the MCP server.

Generation and edits return a task ID, not a finished song. Query suno_get_task (or suno_get_tasks_batch for multiple IDs) until the task reports success and final media URLs. An intermediate audio URL may be only a preview; a failed task should stop polling. Do not repeat the generation call to check progress, because it may submit and bill another task.

Example request to your MCP client:

Use suno_generate_music to create a short upbeat acoustic birthday song. Give me the task ID, check it with suno_get_task, and share the final audio only after the task completes.

For custom lyrics:

Use suno_generate_custom_music with title “Storm”, style “energetic rock”, and these lyrics: [Verse] Thunder in the night [Chorus] We are the storm. Then follow the returned task ID to completion.

negative_tags excludes styles or genres in custom generation (custom=true) and in suno_replace_section. The API currently sets no fixed character limit for this field, but overly long content may still fail; keep the description concise.

Extensions (suno_extend_music, suno_upload_extend) require a positive continue_at in seconds; fractional boundaries such as 30.792 are preserved. Lyrics affect only new content after that boundary, not the original portion. Replacement requires 0 <= replace_section_start < replace_section_end. suno_samples_music selects an interval from one source audio: samples_start defaults to 0, and samples_end is required and must be greater than start. Interval ends must not exceed the source duration. duration (an integer from 10–360) is a target used only for generation; actual length depends on the model.

For suno_generate_inspo, supply 1–4 public reference audio URLs. Use instrumental=true for a no-lyrics request, or custom=true with lyric_prompt and empty lyric for automatic lyrics. The optional persona_id is a voice ID, not an audio ID; voice support with Inspo depends on the service channel. Extensions do not use an additional persona ID.

For suno_all_stems_music, wait for successful terminal completion of the full task. Playable URLs during processing do not mean every stem is complete.

For covers, extensions and stem separation, use the returned audio id as audio_id. A downloadable audio file does not guarantee that its ID remains available for further processing.

Manage saved personas

Call suno_list_personas with user_id to find an existing voice before creating another one; use optional limit (default 50) and offset (default 0) for pagination. Listing uses GET /suno/persona and is free. After confirming the exact persona to remove, call suno_delete_persona with persona_id and optional user_id for ownership verification. Deletion uses DELETE /suno/persona and is also free, but permanent; do not use it to test the connection.

Neither listing nor deletion needs an extra billing-exemption header. Normal API authentication and permissions still apply. suno_create_persona uses POST /suno/persona and remains subject to the API's pricing rules; check current pricing and spending approval before creation. The free list/delete policy does not make voice creation or music generation free.

Cover with a specified voice

Both suno_cover_music and suno_upload_cover accept persona_id for a specified-voice cover. A private voice created by suno_create_voice requires this sequence:

1. Keep the returned persona_id from voice creation.

2. Call suno_upload_audio with the original song's public audio_url, mode: "standard" and that persona_id to associate the source with the voice. persona_id cannot be used with mode: "enhanced".

3. Call suno_upload_cover with the upload's returned data.audio_id and the same persona_id, then follow its task ID to completion.

Do not reuse an older audio ID that was not uploaded with that private voice. Voice creation, upload and cover must use the same service channel. No extra vocal_gender is needed; a gender preference is not a substitute for a voice ID.

Check audio availability before processing

Before a cover or extension, you can call suno_check_audio_availability with the audio UUID from a completed song's id, not the generation task_id:

{"audio_id":"33333333-3333-4333-8333-333333333333"}

Pass these arguments to suno_check_audio_availability. It calls POST /suno/availability synchronously with an API token and currently costs no Credits. Do not poll its returned task_id as though it were a generation job.

A successful response has data.id and data.available=true: the current channel found positive evidence of availability at check time. This does not guarantee that a later cover, extension or other operation will succeed. If availability cannot be confirmed, the API returns an error such as HTTP 503 availability_unknown, never available=false. Do not interpret an error (including rate limits or upstream failures) as proof that the audio is unavailable. Retain returned support identifiers and do not blindly retry or submit a paid operation to resolve uncertainty. Invalid audio IDs return HTTP 400; the MCP tool rejects malformed UUIDs before calling the API.

Processing errors

The audio API documents these HTTP 500 errors:

Stop on terminal failure, retain any returned task_id and trace_id, and contact support with those IDs. Do not blindly resubmit, switch models, or treat an existing download URL as proof that another processing request will work.

Available Models

Vocal Gender Control (v4.5+ only):

• f - Female vocals

• m - Male vocals

Configuration

Environment Variables

Command Line Options

mcp-suno --help

Options:
  --version          Show version
  --transport        Transport mode: stdio (default) or http
  --port             Port for HTTP transport (default: 8000)

Development

Setup Development Environment

# Clone repository
git clone https://github.com/AceDataCloud/SunoMCP.git
cd SunoMCP

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev,test]"

Run Tests

# Run unit tests
pytest

# Run with coverage
pytest --cov=core --cov=tools

# Run integration tests (requires API token)
pytest tests/test_integration.py -m integration

Code Quality

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools

Build & Publish

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

Project Structure

SunoMCP/
├── core/                   # Core modules
│   ├── __init__.py
│   ├── client.py          # HTTP client for Suno API
│   ├── config.py          # Configuration management
│   ├── exceptions.py      # Custom exceptions
│   ├── server.py          # MCP server initialization
│   └── utils.py           # Utility functions
├── tools/                  # MCP tool definitions
│   ├── __init__.py
│   ├── audio_tools.py     # Audio generation tools
│   ├── info_tools.py      # Information tools
│   ├── lyrics_tools.py    # Lyrics generation tools
│   ├── media_tools.py     # Media conversion tools
│   ├── persona_tools.py   # Persona management tools
│   ├── custom_model_tools.py # Custom music model tools
│   └── task_tools.py      # Task query tools
├── tests/                  # Test suite
│   ├── conftest.py
│   ├── test_client.py
│   ├── test_config.py
│   ├── test_integration.py
│   └── test_utils.py
├── deploy/                 # Deployment configs
│   └── production/
│       ├── deployment.yaml
│       ├── ingress.yaml
│       └── service.yaml
├── .env.example           # Environment template
├── .gitignore
├── CHANGELOG.md
├── Dockerfile             # Docker image for HTTP mode
├── docker-compose.yaml    # Docker Compose config
├── LICENSE
├── main.py                # Entry point
├── pyproject.toml         # Project configuration
└── README.md

API Reference

This server wraps the AceDataCloud Suno API:

• Suno Audios API - Music generation

• Suno Lyrics API - Lyrics generation

• Suno Tasks API - Task queries

• Suno Persona API - Persona management

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing)

5. Open a Pull Request

Documentation

Documentation

License

MIT License - see LICENSE for details.

Links

• AceDataCloud Platform

• Suno Official

• Model Context Protocol

• MCP Python SDK

Made with love by AceDataCloud

Cline setup / Cline 图文接入

Suno by Ace Data Cloud — English guide · 完整中文图文步骤. The Cline marketplace submission is pending review as of 2026-10-18; the guide labels the manual fallback separately. / Cline 官方目录投稿仍待审核，手动接入不等于已上架。

Additional audio operations and controls

• suno_add_stem: generate a selected voice/instrument stem with optional style, influence controls, variety, and explicitly opted-in max_mode.

• suno_extract_stem: extract a selected stem and complementary remainder.

• suno_generate_sound: create one-shot or loop sound effects with optional BPM, musical key, and MP3 output selection.

• suno_adjust_speed: change playback speed from 0.25 to 4, optionally preserving pitch.

Prompt generation accepts variety; custom generation also accepts max_mode and audio_weight. Enhanced max_mode has a higher API price and remains off unless explicitly requested. Existing model defaults are unchanged.

suno_generate_with_custom_model accepts instrumental generation or lyric_prompt in place of supplied lyrics, plus negative_tags, vocal_gender, weirdness, style_influence, duration, and callback_url. Title and style are optional.

Studio projects (Beta)

suno_manage_project(request=..., idempotency_key=...) covers create, retrieve, save, upload, add_track, generate_track, replace_section, commit_candidate, remove_track, and render. Its action-specific schema requires only the fields applicable to that operation.

1. Create a project, then retrieve and retain its complete state and latest version_id.

2. Save complete state, upload material, or add tracks using the current version.

3. For generation, supply a source audio ID and a completed project render audio ID. Source ranges use seconds; project timeline ranges use beats.

4. Poll accepted task IDs with suno_get_task until finished_at is set and inspect response.success. Generating candidates does not modify the project.

5. Choose a candidate and explicitly commit it to a track, then render with the latest version. Candidate playback alone does not prove a project is renderable.

Every write requires a caller-selected idempotency_key. Retry an uncertain submission with the same key and identical request, or poll its original task ID; never automatically generate a new key and resubmit a billable operation. On a version conflict, retrieve the current project and re-plan the change.

suno_get_tasks_batch returns full JSON task records with polling guidance, preserving model objects, project state/candidates, and media fields such as MIDI.