A Model Context Protocol (MCP) server for AI music generation using Suno through the AceDataCloud API.
Generate AI music, lyrics, and manage audio projects directly from Claude, VS Code, or any MCP-compatible client.
- Music Generation - Create AI-generated songs from text prompts
- Custom Lyrics & Style - Full control over lyrics, title, and music style
- Song Extension - Continue existing songs from any timestamp
- Cover/Remix - Create cover versions with different styles
- Lyrics Generation - Generate structured lyrics from descriptions
- Persona Management - Save and reuse voice styles
- Task Tracking - Monitor generation progress and retrieve results
Get your API token from AceDataCloud Platform:
- Sign up or log in
- Navigate to Suno Audios API
- Click "Acquire" to get your token
# Clone the repository
git clone https://github.com/AceDataCloud/mcp-suno.git
cd mcp-suno
# Install with pip
pip install -e .
# Or with uv (recommended)
uv pip install -e .# Copy example environment file
cp .env.example .env
# Edit with your API token
echo "ACEDATACLOUD_API_TOKEN=your_token_here" > .env# Run the server
mcp-suno
# Or with Python directly
python main.pyAdd to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"suno": {
"command": "mcp-suno",
"env": {
"ACEDATACLOUD_API_TOKEN": "your_api_token_here"
}
}
}
}Or if using uv:
{
"mcpServers": {
"suno": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-suno", "mcp-suno"],
"env": {
"ACEDATACLOUD_API_TOKEN": "your_api_token_here"
}
}
}
}| Tool | Description |
|---|---|
generate_music |
Generate music from a text prompt (Inspiration Mode) |
generate_custom_music |
Generate with custom lyrics, title, and style |
extend_music |
Extend an existing song from a timestamp |
cover_music |
Create a cover/remix version |
concat_music |
Merge extended segments into complete audio |
generate_with_persona |
Generate using a saved voice style |
| Tool | Description |
|---|---|
generate_lyrics |
Generate song lyrics from a prompt |
| Tool | Description |
|---|---|
create_persona |
Save a voice style for reuse |
| Tool | Description |
|---|---|
get_task |
Query a single task status |
get_tasks_batch |
Query multiple tasks at once |
| Tool | Description |
|---|---|
list_models |
List available Suno models |
list_actions |
List available API actions |
get_lyric_format_guide |
Get lyrics formatting guide |
User: Create a happy birthday song
Claude: I'll generate a birthday song for you.
[Calls generate_music with prompt="A happy birthday celebration song"]
User: Create a rock song with these lyrics:
[Verse]
Thunder in the night
Electric soul ignite
[Chorus]
We are the storm
Claude: I'll create a rock song with your lyrics.
[Calls generate_custom_music with lyrics, title="Storm", style="rock, powerful"]
User: Continue this song from the 2-minute mark with a bridge section
Claude: I'll extend the song with a bridge.
[Calls extend_music with audio_id, continue_at=120, lyric="[Bridge]..."]
| Model | Version | Max Duration | Features |
|---|---|---|---|
chirp-v5 |
V5 | 8 minutes | Latest, best quality |
chirp-v4-5-plus |
V4.5+ | 8 minutes | Enhanced quality |
chirp-v4-5 |
V4.5 | 4 minutes | Vocal gender control |
chirp-v4 |
V4 | 150 seconds | Stable |
chirp-v3-5 |
V3.5 | 120 seconds | Fast |
chirp-v3 |
V3 | 120 seconds | Legacy |
Vocal Gender Control (v4.5+ only):
f- Female vocalsm- Male vocals
| Variable | Description | Default |
|---|---|---|
ACEDATACLOUD_API_TOKEN |
API token from AceDataCloud | Required |
ACEDATACLOUD_API_BASE_URL |
API base URL | https://api.acedata.cloud |
SUNO_DEFAULT_MODEL |
Default model for generation | chirp-v4-5 |
SUNO_REQUEST_TIMEOUT |
Request timeout in seconds | 1800 |
LOG_LEVEL |
Logging 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/mcp-suno.git
cd mcp-suno
# 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/*MCPSuno/
├── 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
│ ├── persona_tools.py # Persona management tools
│ └── task_tools.py # Task query tools
├── tests/ # Test suite
│ ├── conftest.py
│ ├── test_client.py
│ ├── test_config.py
│ ├── test_integration.py
│ └── test_utils.py
├── .env.example # Environment template
├── .gitignore
├── CHANGELOG.md
├── LICENSE
├── main.py # Entry point
├── pyproject.toml # Project configuration
└── README.md
This server wraps the AceDataCloud Suno API:
- Suno Audios API - Music generation
- Suno Lyrics API - Lyrics generation
- Suno Tasks API - Task queries
- Suno Persona API - Persona management
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing) - Open a Pull Request
MIT License - see LICENSE for details.
Made with love by AceDataCloud