MCPSuno

使用说明内容（Markdown格式）

• 项目简介

  • MCPSuno 是一个基于 MCP 的服务器实现，聚合并暴露一组用于音乐生成与管理的工具（如生成音乐、扩展、改编、歌词、人物声线等），并提供信息性 Prompts，供 LLM 客户端通过 MCP 协议进行调用与管理。
  • 服务器通过 AceDataCloud 的 Suno API 提供实际的音乐、歌词与任务等功能的调用能力，核心职责包括资源/工具注册、类型化提示和模板渲染，以及通过 JSON-RPC 与客户端通信。

• 主要功能点

  • MCP 核心能力：注册并暴露 Tools（工具）与 Prompts（提示模板），实现资源管理、数据访问、工具执行、Prompts 渲染等能力。
  • Suno API 封装：通过 HTTP 客户端向 Suno API 发送请求，实现 suno_generate_music、suno_generate_custom_music、suno_extend_music、suno_cover_music、suno_concat_music、suno_generate_with_persona、suno_generate_lyrics、suno_create_persona、suno_get_task、suno_get_tasks_batch、suno_list_models、suno_list_actions、suno_get_lyric_format_guide 等工具。
  • 多传输协议支持：标准输入/输出（stdio）和 HTTP 传输模式，客户端可通过传输模式与端口进行配置。
  • 安全与配置：需要 ACEDATACLOUD_API_TOKEN 环境变量来访问 Suno API；默认模型、请求超时、日志级别等通过环境变量进行配置。
  • Prompts 与工作流示例：提供 suno_music_generation_guide、suno_workflow_examples、suno_style_suggestions 等 prompts，帮助 LVL（LLM）理解如何选择工具和组织工作流。

• 安装步骤

  • 克隆仓库并进入项目目录
  • 以开发模式安装依赖：使用 Python 的开发模式安装
  • 配置环境变量：在根目录创建或编辑 .env，设置 ACEDATACLOUD_API_TOKEN（以及可选的 SUNO_DEFAULT_MODEL、SUNO_REQUEST_TIMEOUT、ACEDATACLOUD_API_BASE_URL 等）
  • 运行服务器
    • 直接运行：python main.py
    • 亦可通过 MCP 客户端指定传输模式运行，例如 stdio 模式（默认）或 http 模式（通过 --transport http 指定并可设置端口）

• 服务器配置（MCP 客户端需要的启动信息，配置以 JSON 格式表达，包含 server name、command、args 等）

  • server_name: suno
  • command: mcp-suno
  • args: ["--transport", "stdio"] // 使用标准输入输出传输（默认模式），如需通过 HTTP 访问改为 ["--transport", "http", "--port", "8000"]
  • 注释：MCP 客户端无需提供 API_TOKEN 等敏感信息在配置中，Token 应通过客户端环境或服务器端环境变量注入；服务器的启动命令应与部署环境相匹配。
  • 该配置确保 MCP 客户端能够按规范启动并连接到 MCP Suno 服务器，进行请求/响应的 JSON-RPC 交互。

• 基本使用方法

  • 启动服务器后，确认控制台输出显示服务器就绪、可连接信息。
  • 使用 MCP 客户端向 suno_generate_music、suno_generate_lyrics、suno_get_task 等工具发送请求，服务端将调用 Suno API，并返回标准的 JSON-RPC 响应。
  • 开发过程中可结合 Prompt 模板（suno_music_generation_guide 等）来引导 LLM 选择合适的工具。
  • 如需在 Claude/VS Code 等环境中使用，请按照文档将 MCP 服务器配置到客户端的 mcpServers.json 中，使用命令启动服务器并设置环境变量。