Suno by Ace Data Cloud

Suno by Ace Data Cloud

简体中文安装与首用指南

通过 AceDataCloud API 使用 Suno 生成 AI 音乐的 Model Context Protocol (MCP) 服务。

可直接通过 Claude、VS Code 或任何兼容 MCP 的客户端生成 AI 音乐和歌词，并管理音频项目。

在 Glama 中使用 Suno

查找 Ace 提供的 Suno 来源列表或远程连接器。请参阅 Glama 安装、API Token 和首用指南。公开发现与个人连接成功是两项独立检查；生成内容会使用你的 Ace 账户余额。

在 goose 中使用 Suno

使用独立的 Suno by Ace Data Cloud 原生 goose 插件：安装与 API Token 指南 · 简体中文。该插件复用此 MCP 服务，并不意味着它已纳入 goose Marketplace 或默认提供商。

在官方 MCP Registry 中查找 Suno 集成

打开官方 MCP Registry 中的 Suno，展开匹配的 io.github.AceDataCloud 条目，并在支持 MCP 目录的客户端中使用其 Packages 或 Remotes 安装信息。这是由 Ace Data Cloud 提供的 Suno 集成；并非模型供应商的认可。Registry 是目录，而不是运行工具的应用。

搜索 mcp-suno（或 io.github.AceDataCloud/mcp-suno）以找到准确条目。目前，官方 Registry 搜索会匹配服务名称；显示标题中的空格不会生成额外的搜索别名。如果你的客户端不支持该目录，请使用下方针对客户端的连接说明，并前往 Applications → General application 查看 Token、服务权限、余额和当前价格。查询异步结果时，请保留原始任务 ID。

功能

• 音乐生成 - 根据文本提示词创作 AI 生成的歌曲
• 自定义歌词与风格 - 全面控制歌词、标题和音乐风格
• 歌曲扩展 - 从任意时间戳继续创作现有歌曲
• 翻唱／混音 - 以不同风格创作翻唱版本
• 歌词生成 - 根据描述生成结构化歌词
• Persona 管理 - 保存并重复使用人声风格
• 自定义音乐模型 - 创建并重复使用应用自有的自定义音乐模型
• 任务跟踪 - 监控生成进度并获取结果

工具参考

工具	描述
suno_generate_music	使用 Suno 的 Inspiration Mode，根据文本提示生成 AI 音乐。
suno_generate_custom_music	完全控制歌词、标题和风格，生成 AI 音乐（Custom Mode）。
suno_extend_music	从指定时间戳开始，为现有歌曲添加新歌词并进行扩展。
suno_cover_music	以不同风格为现有歌曲创作翻唱或混音版本。
suno_concat_music	将扩展后的歌曲片段拼接成一个完整的音频文件。
suno_generate_with_persona	使用已保存的艺人 Persona 生成音乐，以保持人声风格一致。
suno_remaster_music	对现有歌曲进行重新母带处理；v5/v5.5 需要指定变化类别。
suno_stems_music	将歌曲分离为独立音轨（人声和乐器）。
suno_replace_section	用新生成的内容替换歌曲中的指定时间范围。
suno_upload_extend	为上传的音频（你自己的音乐）添加新生成的 AI 内容并进行扩展。
suno_upload_cover	为上传的音频（你自己的音乐）创建 AI 翻唱。
suno_mashup_music	使用必填的创意方向提示词，混合且仅混合两首歌曲。
suno_all_stems_music	返回两组不同的 12 轨候选音轨集，在任务结果中分别标记为 stem_set 1 和 2。
suno_generate_lyrics	根据文本提示生成歌曲歌词。
suno_get_mp4	获取生成歌曲的 MP4 视频版本。
suno_get_timing	获取生成歌曲的时间信息和字幕数据。
suno_extract_vocals	提取指定的人声片段，时长必须短于 30 秒。
suno_get_wav	获取生成歌曲的无损 WAV 格式。
suno_get_mp3	获取生成歌曲的压缩 MP3 格式。
suno_get_midi	获取从生成歌曲中提取的 MIDI 数据。
suno_create_persona	根据现有音频的人声风格创建新的艺人 Persona。
suno_create_custom_model	使用 6 到 24 个经过授权的音频 URL，创建可重复使用的自定义音乐模型。
suno_get_custom_model	根据 ID 获取一个自定义音乐模型。
suno_list_custom_models	列出当前 Suno 应用的自定义音乐模型。
suno_generate_with_custom_model	使用已就绪的自定义音乐模型生成歌曲。
suno_delete_custom_model	归档自定义音乐模型，使其无法再使用。
suno_optimize_style	优化音乐风格描述，以获得更好的生成结果。
suno_mashup_lyrics	通过组合两组歌词生成混搭歌词。
suno_upload_audio	以标准或增强模式上传外部音频，以供后续操作使用。
suno_get_task	查询音乐生成任务的状态和结果。
suno_get_tasks_batch	一次查询多个音乐生成任务。
suno_list_models	列出所有可用的 Suno 模型及其功能。
suno_list_actions	列出所有可用的 Suno API 操作及对应工具。
suno_get_lyric_format_guide	获取 Suno 音乐生成歌词格式指南。

几分钟内完成连接

托管服务的地址是 https://suno.mcp.acedata.cloud/mcp。按照客户端示例操作前，任选一种认证方式：

方式	适用场景	需要提供的信息
浏览器登录（OAuth）	MCP 客户端支持远程 OAuth；如果客户端要求自动注册，请使用 DCR	服务 URL；在浏览器中登录 AceDataCloud 并批准访问。无需将密钥粘贴到 MCP 配置中。
API 令牌	客户端无法完成远程 OAuth 流程，或集成需要明确的凭据	在客户端的 Bearer 标头中提供 AceDataCloud API 令牌。请将其保存在用户级机密存储或环境变量中。
本地 stdio	希望 MCP 进程在本机运行	安装 mcp-suno，并向该进程传入 ACEDATACLOUD_API_TOKEN。

托管服务始终会收到 Bearer 令牌：使用 OAuth 时，客户端会在登录后获取并发送令牌；使用 API 令牌配置时，则由你提供令牌。**DCR 是客户端注册机制，不是单独的 AceDataCloud API 密钥。**用户同意后，托管服务目前会为你的账户复用或创建 API 凭据；如果账户无法获取凭据，此过程可能会失败。某些客户端提供已发布的客户端身份或手动填写的客户端 ID，这些是特定于客户端的替代方式，不意味着还需要第二个 API 令牌。浏览器登录并不免除 AceDataCloud 账户要求。音乐生成会使用你的 AceDataCloud 账户，并可能产生使用费用。生成前，请查看当前的 Suno 定价与限制。

浏览器登录：托管服务

支持远程 MCP OAuth 的客户端可使用此方式。先只添加服务 URL；不要同时设置 Authorization 标头。如果客户端无法完成发现或注册，请使用下方的 API 令牌方式。

Claude 和 Claude Desktop 聊天

在 Claude 中使用远程自定义连接器，路径为 Customize → Connectors → Add custom connector（或使用组织的连接器设置）。输入托管服务 URL，选择登录；如果 Claude 询问 OAuth 客户端的注册方式，请选择自动注册。完成 AceDataCloud 登录和授权流程，然后在对话中启用连接器。Claude Desktop 的 claude_desktop_config.json 用于配置本地 MCP 进程；Claude 的远程自定义连接器不在此处安装。Claude 连接器指南。

Claude Code

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

在 Claude Code 中，/mcp 会显示连接状态和可用工具。若要设置项目级配置，请将 {"mcpServers":{"suno":{"type":"http","url":"https://suno.mcp.acedata.cloud/mcp"}}} 合并到 <project>/.mcp.json；合并时保留已有条目。Claude Code 和 Claude Desktop 聊天使用独立的 MCP 配置。Claude Code MCP 指南。

Cursor

在 Cursor 的 MCP 设置中，使用托管服务 URL 添加远程服务，并完成 OAuth 提示。若要设置项目级配置，请将以下内容合并到 <project>/.cursor/mcp.json；若用于你自己的设备，请使用 ~/.cursor/mcp.json：

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

仅包含 URL 的项目配置不含令牌。之后如果添加了真实令牌，请勿提交项目配置。Cursor MCP 指南。

使用 GitHub Copilot 的 VS Code

运行 MCP: Add Server，选择 HTTP，然后输入托管 URL。个人使用时保存到用户配置文件，团队使用时保存到工作区配置；按提示批准服务并完成登录。新的工作区配置使用 <project>/.mcp.json；VS Code 也会读取其 .vscode/mcp.json 格式。以下是本地工作区的 VS Code 格式：

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

运行 MCP: List Servers，检查连接和工具加载情况。VS Code MCP 设置和配置参考。

Codex CLI 或 Codex 应用

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

Codex 将用户 MCP 设置保存在 ~/.codex/config.toml 中，并可在 /mcp 中显示服务。Codex 官方 MCP 指南。

API 令牌：托管服务

1. 打开 Ace Data Cloud → Applications。登录，或先注册账户。
2. 找到 通用应用。如果尚未创建，请选择 初始化通用应用。通用密钥可使用账户可用的服务；专用应用的密钥则仅限其对应服务。检查所需的服务/模型访问权限和当前价格。
3. 从应用卡片中复制 API 密钥，或打开 密钥 / 管理密钥 → 创建，为此集成创建单独的密钥。为其设置易于识别的名称，以便独立撤销或轮换。
4. 创建密钥时，检查 过期时间、设置用量限制和允许的 API。仅启用所需限制，并允许你将调用的操作，然后点击 创建，并从密钥列表中复制令牌。查询任务并不代表有权限提交生成请求。确认应用余额足以支付首次请求；任何试用额度以账户当前显示为准。
5. 只复制令牌值，不要包含引号、空格或 Bearer 。API 密钥 / API 令牌字段需要此原始值；只有手动配置 HTTP Authorization 标头时才需要 Bearer 前缀。platform-... 账户管理令牌不能代替生成 API 密钥。

将密钥保存在客户端的凭据存储中，或保存到下方所示的环境变量中。切勿将其放入提示词、共享工作流、截图或 Git 提交中。如果身份验证失败，请先检查复制的完整值、应用/服务访问权限、过期时间、用量限制和余额，再创建其他密钥。

如果你需要固定凭据，或客户端无法完成 OAuth，请使用此方式。固定标头无效时，不会自动回退到浏览器登录。

对于 Claude Code，请在启动 Claude Code 的环境中设置变量，然后添加服务。添加服务时，Shell 会展开令牌，因此请将保存的用户级 MCP 配置视为机密；如果不希望在客户端配置中保存密钥，请使用上方的浏览器登录方式：

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"

对于共享项目配置，只在 <project>/.mcp.json 中放入变量引用，并将令牌保存在每位用户的环境中。与上方的 CLI 示例不同，Claude Code 会在读取 .mcp.json 时展开 ${ACEDATACLOUD_API_TOKEN}。将此条目与现有服务合并：

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

对于 Cursor，请在用户级 ~/.cursor/mcp.json（或未提交的项目配置）中使用其 ${env:ACEDATACLOUD_API_TOKEN} 语法：

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

对于 VS Code，建议使用用户配置文件中的 MCP 配置和遮蔽输入，而不是将令牌写入 JSON。将以下字段合并到通过 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}"}
    }
  }
}

此交互式输入专用于 VS Code 的用户／工作区格式；请勿将其复制到 Agent Host 的 .mcp.json 中。VS Code 会提示一次，并安全存储该值以供后续使用。VS Code 配置参考。

其他客户端使用不同的架构。对于 Cline，请打开 MCP Servers → Configure → Configure MCP Servers（Cline CLI：~/.cline/data/settings/cline_mcp_settings.json），并在 mcpServers 下使用 type: "streamableHttp"；Cline 指南提供了完整配置。对于 JetBrains AI Assistant，请转到 Settings → Tools → AI Assistant → Model Context Protocol (MCP)，并使用托管 URL 添加远程服务；检查其连接状态，如果你的版本无法完成 OAuth，则使用 API 令牌方式。JetBrains 指南。对于 Zed，请在设置中使用 context_servers 和托管 URL；省略 Authorization 即可启动其 OAuth 流程。Zed 指南。

本地 stdio 服务

本地模式需要 API 令牌。在客户端仅支持本地进程，或你希望 MCP 进程运行在自己的机器上时使用；它仍会调用 AceDataCloud API，不会在本地运行 Suno。

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

对于 Claude Desktop 的本地 MCP 配置，请将以下内容合并到通过其开发者设置打开的文件中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）。这是一个本地 uvx 进程，与上面的远程自定义连接器分开：

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

请妥善保管此用户级文件。在 Windows 上，请在启动本地客户端的 shell 中设置 $env:ACEDATACLOUD_API_TOKEN = 'YOUR_API_TOKEN'。uvx 要求 uv 位于 PATH 中；mcp-suno 必须安装在客户端启动它所使用的环境中。

对于可自托管的 HTTP 服务，请运行 mcp-suno --transport http --port 8000，或构建此仓库的 Dockerfile 并运行生成的镜像。客户端必须发送各自的 Bearer 令牌；请仅在具备适当网络和 TLS 控制措施的情况下公开该服务。

生成前检查连接

1. https://suno.mcp.acedata.cloud/health 返回 {"status":"ok"} 只能检查可访问性，不能验证身份验证。
2. 使用客户端的 MCP 服务列表确认 Suno 工具已显示。suno_list_models 和 suno_list_actions 返回静态参考数据；它们只能确认工具已加载，不能确认下游 API 凭据或余额有效。
3. 准备就绪后，请客户端使用简短提示词调用 suno_generate_music。保存返回的任务 ID，然后调用 suno_get_task 直至任务完成。这是首次端到端 API 检查，可能会产生费用。在执行此步骤前，请查看当前的 Suno 服务限额和定价。

如果看到 401，请检查客户端是否已完成 OAuth 或发送有效令牌，并且不要同时配置两种方式。如果 OAuth 重定向后失败，请在同一客户端会话中重试；如果账户无法创建或获取凭据，请在 AceDataCloud Platform 中解决。工具列表可以正常加载，但 API 调用仍可能因余额、权限或服务可用性而失败，因此请检查返回的错误，不要直接认定为连接失败。

使用工具

客户端中的工具名称带有 suno_ 前缀。首先使用 suno_list_models 或 suno_list_actions 确认连接。生成音乐时，使用 suno_generate_music 处理提示词，或使用 suno_generate_custom_music 处理自定义歌词和风格。高级操作、媒体转换、人设和自定义模型列于工具参考中，并由 MCP 服务提供。

生成和编辑操作返回的是 任务 ID，而不是完成的歌曲。查询 suno_get_task（如果有多个 ID，则查询 suno_get_tasks_batch），直到任务报告成功并返回最终媒体 URL。中间音频 URL 可能仅为预览；任务失败时应停止轮询。请勿重复调用生成工具来检查进度，因为这可能会提交另一个任务并产生费用。

向 MCP 客户端发送的请求示例：

使用 suno_generate_music 创作一首简短、轻快的原声生日歌曲。告诉我任务 ID，使用 suno_get_task 查询，并仅在任务完成后分享最终音频。

自定义歌词示例：

使用 suno_generate_custom_music，标题为“Storm”，风格为“energetic rock”，歌词如下：[Verse] Thunder in the night [Chorus] We are the storm。然后根据返回的任务 ID 查询，直到任务完成。

negative_tags 仅在自定义模式（custom=true）下排除风格或流派。API 目前未为此字段设置固定的字符数限制，但内容过长仍可能导致失败；请保持描述简洁。

对于翻唱、扩展和音轨分离，请将返回的音频 id 用作 audio_id。音频文件可供下载，并不保证其 ID 仍可用于后续处理。

处理错误

音频 API 文档列出了以下 HTTP 500 错误：

代码	含义
api_error，消息为 the account may have been offline	音频 API 报告该账户可能处于离线状态。
suno_processing_unavailable	音乐处理不可用。
suno_model_unavailable	所选模型无法用于此操作。
suno_processing_failed	音乐处理未返回音频。

遇到终止性失败时应停止操作，保留任何返回的 task_id 和 trace_id，并向支持团队提供这些 ID。请勿盲目重新提交、切换模型，也不要将现有下载 URL 视为其他处理请求一定可行的证明。

可用模型

模型	版本	最长时长	功能
chirp-v6	V6	由 API 定义	当前的 v6 模型
chirp-v6-wild	V6 Wild	由 API 定义	v6 Wild 模型
chirp-v6-mini	V6 Mini	由 API 定义	v6 Mini 模型
chirp-v5-5	V5.5	8 分钟	旧版模型名称
chirp-v5	V5	8 分钟	高品质
chirp-v4-5-plus	V4.5+	8 分钟	增强品质
chirp-v4-5	V4.5	4 分钟	人声性别控制
chirp-v4	V4	150 秒	稳定
chirp-v3-5	V3.5	120 秒	快速
chirp-v3-0	V3	120 秒	旧版

人声性别控制（仅限 v4.5+）：

• f - 女声
• m - 男声

配置

环境变量

变量	说明	默认值
ACEDATACLOUD_API_TOKEN	本地 stdio 令牌；托管请求通过 OAuth 或 Bearer 标头提供	本地 stdio 必填
ACEDATACLOUD_API_BASE_URL	API 基础 URL	https://api.acedata.cloud
ACEDATACLOUD_OAUTH_CLIENT_ID	OAuth 客户端 ID（托管模式）	—
ACEDATACLOUD_PLATFORM_BASE_URL	平台基础 URL	https://platform.acedata.cloud
SUNO_DEFAULT_MODEL	生成时使用的默认模型	chirp-v5-5
SUNO_REQUEST_TIMEOUT	请求超时时间（秒）	1800
LOG_LEVEL	日志级别	INFO

命令行选项

mcp-suno --help

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

开发

设置开发环境

# 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 unit tests
pytest

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

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

代码质量

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools

构建与发布

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

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

项目结构

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 参考

此服务封装了 AceDataCloud Suno API：

• Suno Audios API - 音乐生成
• Suno Lyrics API - 歌词生成
• Suno Tasks API - 任务查询
• Suno Persona API - Persona 管理

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到该分支（git push origin feature/amazing）
5. 创建 Pull Request

文档

文档

许可证

MIT 许可证 - 详情请参阅 LICENSE。

链接

• AceDataCloud Platform
• Suno 官方网站
• Model Context Protocol
• MCP Python SDK

---

由 AceDataCloud 倾情打造

Cline 设置 / Cline 图文接入

Suno by Ace Data Cloud — 英文指南 · 完整中文图文步骤。截至 2026-10-18，Cline 市场提交仍在等待审核；指南将手动备用方案单独列出。/ Cline 官方目录投稿仍待审核，手动接入不等于已上架。