SunoBoard

@yellowkode/suno-mcp

Suno AI 的 MCP 服务 — 直接通过 Claude、VSCode、Cursor 和任何兼容 MCP 的客户端生成音乐。

作者：YellowKode Academy · sunoboard.com

---

这是什么？

@yellowkode/suno-mcp 是一款开源的 Model Context Protocol（MCP） 服务，可将 Claude 和其他 AI 助手 直接连接到 Suno AI 音乐生成 API。

无需手动调用 API，只需告诉 Claude：

“生成一段暗黑氛围的维京风格纯音乐，节奏缓慢，富有电影感，不含人声。”

……Claude 就会自动处理完整的生成流程。

---

前提条件

• Node.js 18+
• 一个 Suno API 密钥 — 有两种选择：

选项	密钥格式	获取方式
SunoBoard（推荐）	sb_...	sunoboard.com — 生成内容会保存到你的控制面板
sunoapi.org（自带密钥）	abc123...	sunoapi.org → 控制面板 → API 密钥

服务会根据密钥前缀自动检测要使用的 API，无需额外配置。

---

快速开始

# One-shot (no install needed)
SUNO_API_KEY=your_key npx @yellowkode/suno-mcp

# Or install globally
npm install -g @yellowkode/suno-mcp

---

设置

Claude Desktop

编辑 claude_desktop_config.json：

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

{
  "mcpServers": {
    "suno": {
      "command": "npx",
      "args": ["@yellowkode/suno-mcp"],
      "env": {
        "SUNO_API_KEY": "your_key_here"
      }
    }
  }
}

Claude Code（终端）

claude mcp add suno \
  -e SUNO_API_KEY=your_key_here \
  -- npx @yellowkode/suno-mcp

Cursor / Cline（VSCode）

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "mcpServers": {
    "suno": {
      "command": "npx",
      "args": ["@yellowkode/suno-mcp"],
      "env": {
        "SUNO_API_KEY": "your_key_here"
      }
    }
  }
}

---

可用工具

工具	描述
generate_music	开始生成音乐 — 返回一个 taskId
get_music_status	根据 taskId 查看生成状态
wait_for_music	自动轮询直至生成完成，并返回音频 URL（最长 5 分钟）
list_recent_music	列出最近生成的曲目
get_credits	查看剩余 API 点数

使用 SunoBoard 密钥（sb_...）还可使用：

工具	描述
generate_sfx	根据文本生成音效（脚步声、硬币声、门声、UI 点击声、呼啸声……），时长为 0.5–10 秒，约 2 秒即可生成。传入 public: true 还可将其分享到 SunoBoard Discover
list_models	查看音乐和音效模型（Suno、Google Lyria、MiniMax、Stable Audio、ElevenLabs、TangoFlux）及各自费用
get_usage	查看本月剩余点数和音效次数、重置日期以及默认模型
search_library	搜索 SunoBoard 公开曲库中的现成曲目（免费）
get_referral_link	获取你的推荐链接（你和朋友都可获得奖励点数）

使用 SunoBoard 密钥时，generate_music 还支持 model = lyria-3-pro、minimax-2.6、stable-audio-2.5 或 elevenlabs-music（在支持的情况下还可使用 duration_seconds）。前往 sunoboard.com/settings 获取密钥 — 也可以跳过安装，直接添加托管连接器 https://mcp.sunoboard.com/mcp（指南）。

generate_music 参数

参数	类型	默认值	说明
prompt	字符串	必填	音乐描述或歌词（自定义模式下）
model	字符串	V4_5	V4 · V4_5 · V4_5PLUS · V4_5ALL · V5 · V5_5
style	字符串	—	风格标签，例如 "ambient dark, slow drums"
title	字符串	—	曲目标题（自定义模式下必填）
instrumental	布尔值	false	生成纯音乐
customMode	布尔值	false	将 prompt 作为原样歌词使用
vocalGender	"male" | "female"	—	人声偏好（仅限自定义模式）
negativeTags	字符串	—	要避免的风格，例如 "heavy metal"
styleWeight	0–1	0.5	风格遵循度
weirdnessConstraint	0–1	0.5	创意程度与可预测性之间的权衡
audioWeight	0–1	0.5	音频质量权重

---

使用示例

基础用法

"生成一首适合学习时听的轻松 lo-fi hip hop 曲目"

Claude 调用 generate_music → wait_for_music 并返回音频 URL。

游戏开发

"为 RPG Boss 战生成戏剧性的战斗音乐，管弦乐风格，无歌词，气氛强烈"

为游戏制作音效（SunoBoard 密钥）

"这是我的 20 种音效清单（草地上的脚步声、拾取硬币、吱呀作响的门……）。用 generate_sfx 逐个生成，并保存到 assets/audio/sfx"

自定义歌词

"用以下歌词生成一首歌：[粘贴歌词]，风格：独立流行，女声演唱"

完全控制

"生成音乐：prompt='宇宙冥想'，style='深空氛围，合成器铺底'，model=V5，纯音乐，weirdness=0.7"

---

环境变量

变量	必填	默认值	说明
SUNO_API_KEY	✅	—	你的 API 密钥（sb_... 或 sunoapi.org 哈希值）
SUNO_API_BASE_URL	❌	自动检测	覆盖 API 基础 URL
MAX_POLL_ATTEMPTS	❌	30	wait_for_music 的最大轮询次数
POLL_INTERVAL_MS	❌	10000	轮询间隔，单位为毫秒

---

可视化仪表板

想要通过可视化方式管理生成的所有音乐吗？

SunoBoard 可为你提供：

• 完整历史记录和内嵌播放器
• 按项目整理（例如，“游戏原声带”“YouTube 频道”）
• 下载 MP3
• 积分跟踪
• 使用相同参数重新生成

使用 sb_ 密钥，即可让所有生成内容自动显示在你的仪表板中。

---

贡献

git clone https://github.com/YellowKode-Academy/suno-mcp
cd suno-mcp
npm install
npm run dev

测试：npm test

---

许可证

MIT © YellowKode Academy · Wunka Tech

由 Kelvin Biffi 倾情打造 ❤️