Content
# Suno Music Generator MCP Server
This is a server based on the Model Context Protocol (MCP) that allows you to generate music using the Suno API by invoking tools.
## ✨ Features
* Interact with the Suno API via MCP.
* Supports custom mode (providing lyrics, style, title) and inspiration mode (providing a description).
* Supports continuing the generation of existing song fragments.
* Automatically polls task status and returns the audio URL upon completion.
* Configurable API Key and model version.
## 🚀 Getting Started
### 📋 Prerequisites
* [Node.js](https://nodejs.org/) (LTS version recommended)
* [npm](https://www.npmjs.com/) (usually installed with Node.js) or [yarn](https://yarnpkg.com/)
### ⚙️ Installation
1. Clone this repository (if you haven't already):
```bash
git clone <your-repository-url>
cd <repository-directory>
```
2. Install project dependencies:
```bash
npm install
# or use yarn
# yarn install
```
### 🔑 Configuration
1. Create a file named `config.env` in the root directory of the project.
2. Add your Suno API Key in that file:
```env
SunoKey=sk_YOUR_SUNO_API_KEY_HERE
```
Replace `sk_YOUR_SUNO_API_KEY_HERE` with your actual Suno API Key.
### ▶️ Running the MCP Server
To start the MCP server, run the following command in the root directory of the project:
```bash
npm start
# or, if you have defined a "dev" script in package.json and want to use ts-node-dev for hot-reload development:
# npm run dev
# or directly run the compiled JavaScript file:
# node build/index.js
```
Once the server is started, it will communicate with compatible MCP clients via standard input/output (stdio).
### 🔌 Deploying in MCP Client
To use this server in your MCP client (such as an AI assistant or development tool that supports MCP), you typically need to add a server entry in the client's configuration file. Here is an example configuration; please adjust it according to your client's specific requirements:
```json
{
"YOUR_UNIQUE_SERVER_ID": { // Replace with the unique ID generated by your client
"name": "Suno-MCP", // The name you assign to this server
"type": "stdio", // Communication type, which is "stdio" for this server
"description": "Let AI sing", // A brief description of the server
"isActive": true, // Whether to activate this server
"command": "node", // The command to start the server
"args": [
"<path-to-your-project>/MCP-Suno/build/index.js" // Absolute or relative path to the compiled index.js file
],
"env": {
// Environment variables can be passed to the server process
// If you set SunoKey here, it may override the value in config.env
// "SunoKey": "sk_YOUR_SUNO_API_KEY_FROM_CLIENT_CONFIG"
},
"cwd": "<path-to-your-project>/MCP-Suno" // Optional: Set the working directory for the server, usually the project root
}
}
```
**Important Notes:**
* **`YOUR_UNIQUE_SERVER_ID`**: This is usually automatically generated by your MCP client or requires you to provide a unique identifier.
* **`command`**: For Node.js projects, this is typically `node`.
* **`args`**: The first parameter in the array should be the path to the compiled `build/index.js` file. Make sure to replace `<path-to-your-project>` with your actual project path.
* **`env`**: You can set environment variables here. The server script ([`index.ts`](index.ts:22)) will attempt to load `SunoKey` from the `config.env` file in the project root. If `SunoKey` is also set in the client configuration's `env`, its behavior (whether it overrides) may depend on Node.js's handling of environment variable priority and the configuration of the `dotenv` package. To ensure `SunoKey` is loaded correctly, it is recommended to configure it primarily through the `config.env` file in the project root, as described in the “[🔑 Configuration](#-configuration)” section.
* **`cwd`**: Setting the working directory to the project root (the directory containing the `build` folder and `config.env`) is usually a good idea to ensure relative paths (like `../config.env` relative to `build/index.js`) resolve correctly.
Please refer to your MCP client documentation for detailed instructions on how to add and configure MCP servers.
## 🛠️ Tool Description
This MCP server provides the following tool:
### `generate_music_suno`
Generates songs using the Suno API.
**Description:**
```
Generates a song using the Suno API. Provide lyrics, style, and title for custom mode, or a description for inspiration mode. Returns the audio URL upon completion. Polling for results may take a few minutes.
When returning an audio URL, please use the following HTML format for user convenience:
```html
<audio controls>
<source src="YOUR_AUDIO_URL_HERE" type="audio/mpeg">
</audio>
<br>
<a href="YOUR_AUDIO_URL_HERE" download="SONG_TITLE.mp3">
Click here to download meow!
</a>
```
```
**Input Parameters (`inputSchema`):**
* `prompt` (string): Lyrics content. Required in custom mode. Example: `'[Verse 1]\nUnder the starry sky...'`
* `tags` (string): Music style tags, comma-separated. Required in custom mode. Example: `'acoustic, folk, pop'`
* `title` (string): Song title. Required in custom mode. Example: `'Starry Night Serenade'`
* `mv` (string, optional): Model version. Optional values: `"chirp-v3-0"`, `"chirp-v3-5"`, `"chirp-v4"`. Default is `'chirp-v4'`.
* `make_instrumental` (boolean, optional): Whether to generate instrumental music. Default is `false`.
* `gpt_description_prompt` (string, optional): Description for inspiration mode. If this parameter is provided, `prompt`, `tags`, and `title` are not strictly required. Example: `'A cheerful upbeat song about a sunny day.'`
* `task_id` (string, optional): Task ID of the previous song to continue. If provided, `continue_at` and `continue_clip_id` are also required.
* `continue_at` (number, optional): The time point (in seconds) to continue from the song. Requires `task_id` and `continue_clip_id`.
* `continue_clip_id` (string, optional): Clip ID of the song fragment to continue. Requires `task_id` and `continue_at`.
**Validation Logic:**
* If `gpt_description_prompt` is not provided, `prompt`, `tags`, and `title` are all required.
* If `task_id` is provided, `continue_at` and `continue_clip_id` must also be provided.
**Output:**
On success, returns a text content containing the audio URL. If an error occurs, returns an error message.
## 💡 Example MCP Requests
**Generate a Custom Song:**
```json
{
"type": "call_tool",
"params": {
"name": "generate_music_suno",
"arguments": {
"prompt": "[Verse 1]\nIn the digital realm, where code streams flow,\nA kitty coder, with a vibrant glow.\n[Chorus]\nMeow, meow, MCP, oh so grand,\nGenerating tunes across the land!",
"tags": "electronic, upbeat, synthwave",
"title": "MCP Kitty's Anthem",
"mv": "chirp-v4"
}
}
}
```
**Generate a Song Using Inspiration Mode:**
```json
{
"type": "call_tool",
"params": {
"name": "generate_music_suno",
"arguments": {
"gpt_description_prompt": "A lofi chill beat for late night coding sessions",
"mv": "chirp-v3-5"
}
}
}
```
**Continue Generating a Song:**
```json
{
"type": "call_tool",
"params": {
"name": "generate_music_suno",
"arguments": {
"task_id": "your_previous_task_id_here",
"continue_at": 60,
"continue_clip_id": "your_previous_clip_id_here",
"mv": "chirp-v4"
// prompt, tags, title might be needed by Suno API for continuation,
// or it might infer from the original task.
// Check Suno API documentation for specifics on continuation.
}
}
}
```
## 🤝 Contribution
Feel free to submit Pull Requests or Issues to improve this project!
## 📄 License
(Choose a license for your project, such as MIT, Apache 2.0, etc.)
For example: This project is licensed under the MIT License.
