@yellowkode/suno-mcp

MCP Server for Suno AI — Generate music directly from Claude, VSCode, Cursor, and any MCP-compatible client.

by YellowKode Academy · sunoboard.com

What is this?

@yellowkode/suno-mcp is an open-source Model Context Protocol (MCP) server that connects Claude and other AI assistants directly to the Suno AI music generation API.

Instead of manually calling the API, you can just tell Claude:

"Generate a dark ambient viking instrumental, slow drums, cinematic, no vocals"

...and Claude handles the full generation flow automatically.

Prerequisites

• Node.js 18+
• A Suno API key — two options:

| Option | Key format | Where to get | |--------|-----------|--------------| | SunoBoard (recommended) | sb_... | sunoboard.com — generations saved to your dashboard | | sunoapi.org (BYOK) | e57efd1b... | sunoapi.org → Dashboard → API Keys |

The server auto-detects which API to use based on the key prefix. No extra config needed.

Quick start

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

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

Setup

Claude Desktop

Edit 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 (terminal)

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

Cursor / Cline (VSCode)

Add to .cursor/mcp.json or .vscode/mcp.json:

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

Available Tools

| Tool | Description | |------|-------------| | generate_music | Start music generation — returns a taskId | | get_music_status | Check generation status by taskId | | wait_for_music | Auto-poll until ready, returns audio URL (up to 5 min) | | list_recent_music | List recently generated tracks | | get_credits | Check remaining API credits |

generate_music parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | prompt | string | required | Music description or lyrics (in custom mode) | | model | string | V4_5 | V4 · V4_5 · V4_5PLUS · V4_5ALL · V5 · V5_5 | | style | string | — | Style tags e.g. "ambient dark, slow drums" | | title | string | — | Track title (required in custom mode) | | instrumental | boolean | false | Generate without vocals | | customMode | boolean | false | Use prompt as literal lyrics | | vocalGender | "male" | "female" | — | Vocal preference (custom mode only) | | negativeTags | string | — | Styles to avoid e.g. "heavy metal" | | styleWeight | 0–1 | 0.5 | Style adherence | | weirdnessConstraint | 0–1 | 0.5 | Creativity vs. predictability | | audioWeight | 0–1 | 0.5 | Audio quality weight |

Usage Examples

Basic

"Generate a relaxing lo-fi hip hop track for studying"

Claude calls generate_music → wait_for_music and returns the audio URL.

Game development

"Generate dramatic battle music for an RPG boss fight, orchestral, no lyrics, intense"

Custom lyrics

"Generate a song with these lyrics: [paste lyrics], style: indie pop, female vocals"

With full control

"Generate music: prompt='cosmic meditation', style='deep space ambient, synth pads', model=V5, instrumental, weirdness=0.7"

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SUNO_API_KEY | ✅ | — | Your API key (sb_... or sunoapi.org hash) | | SUNO_API_BASE_URL | ❌ | auto-detected | Override API base URL | | MAX_POLL_ATTEMPTS | ❌ | 30 | Max polls for wait_for_music | | POLL_INTERVAL_MS | ❌ | 10000 | Polling interval in ms |

Visual Dashboard

Want to manage all your generated music visually?

SunoBoard gives you:

• Full history with inline player
• Organize by project (e.g. "Game OST", "YouTube Channel")
• Download MP3
• Credit tracking
• Regenerate with same parameters

Use a sb_ key to have all generations appear automatically in your dashboard.

Contributing

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

Tests: npm test

License

MIT © YellowKode Academy · Wunka Tech

Built with ❤️ by Kelvin Biffi