Name: AI音乐生成服务器
Author: CodeKeanu

使用说明

Suno MCP服务器

模型上下文协议（MCP）服务器，使用Suno API提供AI音乐生成功能。该服务器允许Claude和其他MCP客户端通过简单的工具界面生成音乐、检索曲目信息和管理API信用。

✨ 通过GitHub Actions自动构建Docker功能-始终获取最新版本 docker pull!

特性

生成音乐：根据具有可自定义参数的文本提示创建AI生成的音乐
WAV转换：将生成的MP3曲目转换为高质量的WAV格式
轨道状态监测：使用任务ID检查生成进度并检索已完成的跟踪信息
轨道信息：使用曲目ID检索有关生成曲目的详细信息，包括状态、URL和元数据
信用管理：检查API信用余额和使用情况统计
多个型号版本：支持Suno v3.5、v4、v4.5、v4.5plus、v5和v5.5型号（建议使用v5.5以获得最佳质量）
自定义模式：通过精确的歌词、特定的流派标签和高级控件进行微调
高级控制：风格权重、怪异约束、声音性别选择等

先决条件

选项1（Docker-推荐）：已安装Docker和Docker Compose
选项2（原生Python）：Python 3.10或更高版本
Suno API密钥（从 sunoapi.org)
兼容MCP的客户端：Claude Desktop或Claude Code

安装

选项1:Docker Pull（最简单-推荐）

直接从GitHub容器注册表中提取预构建映像-无需代码或构建！

拉取Docker镜像：

docker pull ghcr.io/codekeanu/suno-mcp:latest

创建一个 .env 使用API密钥文件：

# Create a directory for your config
mkdir suno-mcp-config
cd suno-mcp-config

# Create .env file
cat > .env << EOF
SUNO_API_KEY=your_actual_api_key_here
SUNO_API_BASE_URL=https://api.sunoapi.org
EOF

就是这样！跳到用法配置Claude Desktop或Claude Code的部分。

选项2：从源代码构建Docker

从源代码自己构建Docker镜像。

克隆此存储库：

git clone https://github.com/CodeKeanu/suno-mcp.git
cd suno-mcp

配置API密钥：

cp .env.example .env

编辑 .env 并添加您的Suno API密钥：

SUNO_API_KEY=your_actual_api_key_here
SUNO_API_BASE_URL=https://api.sunoapi.org

构建Docker镜像：

docker build -t suno-mcp-server:latest .
# Or use docker-compose:
docker-compose build

注：如果您从源代码构建，请使用 suno-mcp-server:latest 在下面的配置示例中，而不是 ghcr.io/codekeanu/suno-mcp:latest.

选项3：原生Python安装

克隆此存储库：

git clone https://github.com/CodeKeanu/suno-mcp.git
cd suno-mcp

安装依赖项：

pip install -r requirements.txt

配置API密钥：

cp .env.example .env

编辑 .env 并添加您的Suno API密钥：

SUNO_API_KEY=your_actual_api_key_here
SUNO_API_BASE_URL=https://api.sunoapi.org

用法

使用Claude Desktop

Claude Desktop是Claude的官方桌面应用程序，支持MCP服务器。

Docker配置（推荐）

找到您的Claude Desktop配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
添加Suno MCP服务器配置（替换 /absolute/path/to/.env 根据您的实际路径）：

{
  "mcpServers": {
    "suno": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/absolute/path/to/.env",
        "ghcr.io/codekeanu/suno-mcp:latest"
      ]
    }
  }
}

示例路径：

macOS： /Users/yourusername/suno-mcp-config/.env
窗户： C:\\Users\\yourusername\\suno-mcp-config\\.env
Linux： /home/yourusername/suno-mcp-config/.env

重要提示：

使用 绝对路径 （从根开始的完整路径），而不是相对路径
在Windows上，使用双反斜杠(\\)或正斜杠(/)
启动Claude Desktop之前，请确保Docker Desktop正在运行
这 .env 文件必须包含有效的Suno API密钥
首次运行时，图像将自动从GitHub容器注册表中提取

重新启动克劳德桌面 完全为了使更改生效
通过询问Claude来测试集成：
- “你能检查我的Suno API信用吗？”
- “创作一首简短的快乐器乐歌曲”

替代方案：环境变量（不需要.env文件）

如果你不想使用 .env 文件，您可以直接传递API密钥：

{
  "mcpServers": {
    "suno": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SUNO_API_KEY=your_actual_api_key_here",
        "-e",
        "SUNO_API_BASE_URL=https://api.sunoapi.org",
        "ghcr.io/codekeanu/suno-mcp:latest"
      ]
    }
  }
}

原生Python配置

对于原生Python（不含Docker）：

{
  "mcpServers": {
    "suno": {
      "command": "python",
      "args": ["/absolute/path/to/suno-mcp/server.py"],
      "env": {
        "SUNO_API_KEY": "your_actual_api_key_here",
        "SUNO_API_BASE_URL": "https://api.sunoapi.org"
      }
    }
  }
}

使用Claude代码

Claude Code是一个使用Claude进行软件开发的CLI工具。

Docker配置（推荐）

选项1：使用Claude代码设置UI

打开克劳德代码设置
导航到MCP服务器部分
使用以下命令添加新服务器：
- 名称: suno
- 命令: docker
- 参数: ["run", "--rm", "-i", "--env-file", "/absolute/path/to/.env", "ghcr.io/codekeanu/suno-mcp:latest"]
- 替换 /absolute/path/to/.env 与你的实际路径

选项2：手动配置

添加到MCP设置文件（通常 ~/.config/claude-code/mcp_settings.json):

{
  "mcpServers": {
    "suno": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/absolute/path/to/.env",
        "ghcr.io/codekeanu/suno-mcp:latest"
      ]
    }
  }
}

重要提示： 替换 /absolute/path/to/.env 与您的实际路径 .env 文件。

Docker标志说明：

--rm：容器退出时自动删除
-i：保持stdin打开，以便MCP stdio通信
--env-file：从加载环境变量 .env 文件（确保API密钥的安全）

原生Python配置

选项1：使用Claude代码设置UI

打开克劳德代码设置
导航到MCP服务器部分
使用以下命令添加新服务器：
- 名称: suno
- 命令: python
- 参数: ["/absolute/path/to/suno-mcp/server.py"]
- 环境变量:
  - SUNO_API_KEY：您的API密钥
  - SUNO_API_BASE_URL: https://api.sunoapi.org

选项2：手动配置

添加到MCP设置文件中：

{
  "mcpServers": {
    "suno": {
      "command": "python",
      "args": ["/absolute/path/to/suno-mcp/server.py"],
      "env": {
        "SUNO_API_KEY": "your_actual_api_key_here",
        "SUNO_API_BASE_URL": "https://api.sunoapi.org"
      }
    }
  }
}

重要提示：

替换 /absolute/path/to/suno-mcp/server.py 与你的实际路径
添加配置后重新启动Claude Code

可用工具

服务器公开了6个用于音乐生成和管理的MCP工具：

1.生成音乐

通过具有广泛自定义选项的文本提示生成AI音乐。

参数：

核心参数：

prompt （有条件）：音乐的文字描述/歌词
- 带人声的自定义模式：用作精确歌词（根据型号，最多3000-5000个字符）
- 非自定义模式：用作自动生成歌词的核心思想（最多500个字符）
- 自定义模式工具：如果满足以下条件，则不需要 make_instrumental=true
make_instrumental （可选，默认：false）：仅生成器乐而不生成人声
model_version （可选，默认：“v3.5”）：AI模型版本
- 选项：“v3.5”、“v4”、“v4.5”、“v4.5plus”、“v5”、“v5.5”
- 推荐：使用“v5.5”获得最佳音乐质量，或使用“v5”获得卓越的音乐表现力和更快的生成速度
wait_audio （可选，默认值：true）：等待生成完成后返回

自定义模式参数：

custom_mode （可选，默认值：false）：启用高级控制模式
- 启用后，需要 style 和 title 参数
- 允许精确的歌词规范和细粒度的风格控制
style （如果custom_mode=true，则需要）：音乐风格/流派标签（最多200-1000个字符）
- 示例：“管弦乐史诗、电影、强大的弦乐、戏剧合唱团”
title （如果custom_mode=true，则需要）：歌曲标题（最多80个字符）

高级参数：

callback_url （可选）：用于完成通知的Webhook URL
- 备注：Suno API可能需要此参数。如果生成失败，并显示“请输入callBackUrl”，请提供一个URL（例如https://example.com/webhook")
persona_id （可选）：用于风格影响的角色标识符（仅限自定义模式）
negative_tags （可选）：要排除的风格或特征（例如，“攻击性、重金属”）
vocal_gender （可选）：首选声乐性别（“m”或“f”）
style_weight （可选）：风格指导权重（0.00-1.00）
- 更高的值更严格地遵守指定的样式
weirdness_constraint （可选）：创造性偏差容差（0.00-1.00）
- 更高的值允许更多的实验/异常结果
audio_weight （可选）：输入音频影响权重（0.00-1.00）

退货：

异步生成跟踪的任务ID
跟踪信息，如果 wait_audio=true

例子：

Generate a calm piano meditation piece using v5 model

2.获取任务状态

获取音乐生成任务的状态，并在完成后检索曲目信息。

参数：

task_id （必填）：从返回的任务ID generate_music

退货：

任务状态（例如，“TEXT_SUCCESS”）
操作类型和型号信息
生成完成后跟踪详细信息，包括ID、标题、音频URL和元数据

例子：

Check status of task: 684b694f002afbb35b49994b32a6a01e

注：此工具使用任务ID（而不是跟踪ID）。使用此功能监视从开始的异步代 wait_audio=false 或者检索关于最近完成的世代的信息。

3.获取音乐信息

使用曲目ID获取特定曲目的详细信息。

参数：

track_ids （必需）：用于检索信息的曲目ID数组

退货：

详细的跟踪信息，包括状态、URL、持续时间、标签和创建时间

例子：

Get information for tracks: ["7752c889-3601-4e55-b805-54a28a53de85", "be973545-05f9-4a00-9177-81d4ce0ed5c1"]

注：此工具使用特定的跟踪ID（不是任务ID）。轨道ID从返回 generate_music 或 get_task_status.

4.获取信用

检查您的Suno API帐户信用余额。

参数： 无

退货：

剩余API信用

例子：

Check my Suno API credits

5.convert_to_wav

将生成的MP3曲目转换为高质量的WAV格式。需要生成任务ID和特定轨道ID。

参数：

callback_url （必填）：用于转换完成通知的Webhook URL（例如，“https://example.com/webhook")
task_id （必填）：生成任务ID来自 music['data']['taskId'] -标识生成作业的十六进制字符串
audio_id （必填）：来自的曲目ID music['data']['sunoData'][0]['id'] -标识要转换的特定曲目的UUID

退货：

转换任务ID （与generation task_id不同！）用于跟踪WAV转换进度

工作流程示例：

# Step 1: Generate music
music = generate_music(prompt="Epic soundtrack", wait_audio=True)
generation_task_id = music['data']['taskId']        # "aba5fa3d..." (for music generation)
track_id = music['data']['sunoData'][0]['id']       # "8116fdcd..." (specific track)

# Step 2: Convert to WAV
conversion = convert_to_wav(
    callback_url="https://example.com/webhook",
    task_id=generation_task_id,  # Use generation task_id here
    audio_id=track_id             # Use track ID here
)
conversion_task_id = conversion['data']['taskId']   # "4c7c38f9..." (NEW ID for WAV conversion!)

# Step 3: Get WAV download URL
status = get_wav_conversion_status(task_id=conversion_task_id)  # Use CONVERSION task_id!
wav_url = status['data']['response']['audioWavUrl']

🔴 严重警告：

三个不同的ID -生成任务_id、跟踪音频_id和转换任务_id都不同！
必须保存转换任务ID -返回的转换task_id是获取WAV下载URL的唯一方法
无替代检索 -您无法通过audio_id或generation task_id查询WAV状态
如果丢失，WAV将无法恢复 -丢失转换task_id意味着您无法检索WAV URL
409冲突 -如果得到“WAV记录已存在”，则需要ORIGINAL转换任务_id（不是生成任务_id）

要求：

需要两个id（生成任务_id+曲目音频_id）
轨道生成必须完成（使用 wait_audio=true)

6.get_av_conversion_status

获取WAV转换任务的状态，并在完成后检索下载URL。

参数：

task_id （必填）：The 转换任务ID 返回从 convert_to_wav （不是生成task_id！）

退货：

转换任务状态（成功、待定等）
转换完成时的WAV下载URL
跟踪信息和创建时间

例子：

# Use the CONVERSION task_id (from convert_to_wav response)
# NOT the generation task_id (from generate_music response)
status = get_wav_conversion_status(task_id="4c7c38f9529e2ae2c159a56fc6a4b9e6")
wav_url = status['data']['response']['audioWavUrl']

⚠️ 重要：

使用 转换任务id （返回自 convert_to_wav)
不要使用生成task_id（来自 generate_music)-它不起作用
请勿使用audio_id-API不支持按audio_id进行查询

示例工作流

基础音乐生成（推荐）

使用v5模型生成音乐：
```
Generate an epic orchestral battle theme using v5 model in custom mode
```
- Claude将使用带有适当样式标签的自定义模式
- 返回任务ID和跟踪信息
- 使用v5型号获得最佳质量
检查积分：
```
How many Suno credits do I have left?
```

高级：带监控的异步生成

启动异步生成：
```
Generate a 3-minute ambient soundscape, don't wait for completion
```
- 立即返回任务ID
- 世代在后台继续
监控进度：
```
Check status of task: [task-id]
```
- 显示生成进度
- 完成后返回曲目ID和URL
获取曲目详细信息：
```
Get information for tracks: ["track-id-1", "track-id-2"]
```
- 检索详细的元数据和下载URL

了解ID

任务标识：返回 generate_music，与 get_task_status
- 例子： 684b694f002afbb35b49994b32a6a01e
- 用于监控发电进度
曲目编号：特定于每首生成的歌曲，与 get_music_info
- 例子： 7752c889-3601-4e55-b805-54a28a53de85
- Suno通常为每个请求生成2个曲目
- 每个曲目都有自己的唯一ID

Docker部署指南

本节介绍Docker的具体使用和管理。

塑造形象

# Using Docker directly
docker build -t suno-mcp-server:latest .

# Or using Docker Compose (if installed)
docker-compose build
# OR (newer plugin syntax)
docker compose build

手动运行容器

用于测试或独立使用：

# Run with environment file
docker run --rm -i --env-file .env suno-mcp-server:latest

# Or pass environment variables directly
docker run --rm -i \
  -e SUNO_API_KEY=your_api_key_here \
  -e SUNO_API_BASE_URL=https://api.sunoapi.org \
  suno-mcp-server:latest

健康检查

Docker容器包括自动健康监控：

# Check container health status
docker ps

# View health check logs
docker inspect --format='{{json .State.Health}}' suno-mcp-server

# Manual health check
docker exec suno-mcp-server python healthcheck.py

健康检查验证：

环境变量设置正确
所需的Python模块可用
Suno客户端可以正确初始化

Docker编写用法

# Build the image
docker-compose build

# Start the server (for testing)
docker-compose up

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

# Rebuild after code changes
docker-compose build --no-cache

安全最佳实践

永不承诺 .env 到版本控制 -它包含您的API密钥
使用 .env 文件 -在命令历史和脚本中隐藏秘密
非根执行 -容器运行方式为 appuser （UID 1000）
最小图像 -基于 python:3.12-slim 减少攻击面
只读文件系统 -可选；取消注释 docker-compose.yml 如有需要

容器资源管理

这 docker-compose.yml 包括资源限制：

CPU限制：1.0核
内存限制：512MB
CPU预留：0.5核
内存预留：256MB

调整这些 docker-compose.yml 如果你的环境需要的话。

更新容器

更改代码后：

# Rebuild the image
docker-compose build

# Or rebuild without cache
docker-compose build --no-cache

# Restart Claude Code to pick up the new image

Docker问题排查

容器未通过健康检查

# Check health check output
docker logs suno-mcp-server

# Run health check manually
docker run --rm -i --env-file .env suno-mcp-server:latest python healthcheck.py

“无法连接到Docker守护进程”

确保Docker正在运行： sudo systemctl start docker
检查Docker权限： sudo usermod -aG docker $USER （然后注销/登录）

集装箱立即出口

检查日志： docker logs suno-mcp-server
验证 .env 文件存在并且包含有效的API密钥
确保成功构建映像： docker images | grep suno-mcp-server

环境变量未加载

验证 .env docker-compose.yml或docker run命令中的文件路径
检查文件权限： ls -la .env
确保 .env 文件格式正确（值周围没有引号）

故障排除

常见错误

“必须提供SUNO_API_KEY”

码头工人:
- 确保 .env 文件存在于您的项目目录中
- 验证到的绝对路径 .env MCP配置正确
- 检查一下 .env 文件包含： SUNO_API_KEY=your_actual_key
- 确保Docker可以访问该文件（权限）
原生的:
- 确保您的 .env 文件存在并且包含有效的API密钥
- 或验证 SUNO_API_KEY 设置在 env MCP配置的一部分

“无法生成音乐：401未经授权”

验证API密钥是否正确且处于活动状态
检查您的API密钥是否有足够的信用

“API错误（代码400）：请输入callBackUrl”

Suno API需要 callback_url 某些操作的参数
提供webhook URL（可以是占位符，如“https://example.com/webhook")
Claude Code在使用generate_music工具时会自动处理此问题

“连接超时”

音乐创作可能需要时间；默认超时为5分钟
对于更长的世代，set wait_audio: false 并使用 get_task_status 投票以完成

“当custom_mode为True时，必须提供样式”

使用自定义模式时，两者 style 和 title 参数是必需的
提供流派/风格标签（例如，“史诗管弦乐、电影”）

最佳实践

始终指定型号版本：使用 model_version: "v5" 为达到最佳效果
使用自定义模式进行精确控制：支持精确的歌词和详细的风格规范
定期监控信用：每一代消耗积分（通常每一代6个积分）
Suno生成2首曲目：每个请求都会产生两种不同的提示
正确使用任务ID与跟踪ID:
- 任务ID：用于检查生成状态
- 曲目ID：用于检索特定曲目信息

技术细节

服务器信息

服务器名称: suno-mcp-server
版本: 1.0.0
协议：模型上下文协议（MCP）
API：suno API第1版
Python版本: 3.10+
异步支持：使用httpx实现完整的async/await

使用的API端点

/api/v1/generate -音乐一代
/api/v1/generate/record-info -任务/跟踪状态检索
/api/v1/generate/credit -信用余额检查

模型版本映射

服务器自动将用户友好的版本名称转换为API格式：

v3.5 → V3_5 （啁啾v3-5）
v4 → V4 （唧唧声-v4）
v4.5 → V4_5 （chirp-v4-5）
v4.5plus → V4_5PLUS （chirp-v4-5-plus）
v5 → V5 （唧唧唧）
v5.5 → V5_5 - 推荐

信贷成本

标准生成：每次请求约6个学分
每个请求生成2个轨道变化
成本可能因型号版本和世代长度而异

API 参考

此服务器使用Suno API v1。更多信息：

文档: https://docs.sunoapi.org/
API密钥管理: https://sunoapi.org/api-key
支持: support@sunoapi.org

贡献

欢迎投稿！请随时提交问题或拉取请求。

许可证

此MCP服务器按原样提供，以便与Suno API一起使用。有关API使用指南，请参阅Suno的服务条款。

支持

关于以下问题：

此MCP服务器: 打开一个问题
苏诺API：参观https://docs.sunoapi.org/或联系support@sunoapi.org
MCP协议：参观https://modelcontextprotocol.io/

内置于 ❤️ 使用模型上下文协议

使用说明

Suno MCP服务器

特性

先决条件

安装

选项1:Docker Pull（最简单-推荐）

选项2：从源代码构建Docker

选项3：原生Python安装

用法

使用Claude Desktop

Docker配置（推荐）

原生Python配置

使用Claude代码

Docker配置（推荐）

原生Python配置

可用工具

1.生成音乐

2.获取任务状态

3.获取音乐信息

4.获取信用

5.convert_to_wav

6.get_av_conversion_status

示例工作流

基础音乐生成（推荐）

高级：带监控的异步生成

了解ID

Docker部署指南

塑造形象

手动运行容器

健康检查

Docker编写用法

安全最佳实践

容器资源管理

更新容器

Docker问题排查

容器未通过健康检查

“无法连接到Docker守护进程”

集装箱立即出口

环境变量未加载

故障排除

常见错误

“必须提供SUNO_API_KEY”

“无法生成音乐：401未经授权”

“API错误（代码400）：请输入callBackUrl”

“连接超时”

“当custom_mode为True时，必须提供样式”

最佳实践

技术细节

服务器信息

使用的API端点

模型版本映射

信贷成本

API 参考

贡献

许可证

支持

相关 MCP

语音处理服务

LLM增强工具包

Ableton音乐制作辅助工具

音频接口服务器

终端音乐创作工具

语音合成服务器