@yellowkode/suno-mcp-core

Shared core handlers and tool schemas for Suno MCP servers — by YellowKode Academy

What is this?

@yellowkode/suno-mcp-core is the shared business logic layer used by both:

• @yellowkode/suno-mcp — the open-source stdio MCP server (Claude Desktop, Cursor, VSCode)
• SunoBoard hosted MCP — mcp.sunoboard.com (StreamableHTTP transport)

It provides typed handlers for the Suno API and the standard MCP tool schemas. You can use it to build your own Suno MCP server with any transport.

Installation

npm install @yellowkode/suno-mcp-core

Usage

import { createHandlers, toolSchemas } from '@yellowkode/suno-mcp-core';
import type { GenerateMusicParams } from '@yellowkode/suno-mcp-core';

const handlers = createHandlers({
  apiKey: process.env.SUNO_API_KEY!,
  baseUrl: 'https://api.sunoapi.org', // or 'https://api.sunoboard.com' for sb_ keys
  maxPollAttempts: 30,
  pollIntervalMs: 10000,
});

// Use with any MCP server transport
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: toolSchemas }));

server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
  const { name, arguments: args } = params;
  switch (name) {
    case 'generate_music':
      return { content: [{ type: 'text', text: JSON.stringify(await handlers.generateMusic(args as GenerateMusicParams)) }] };
    case 'wait_for_music':
      return { content: [{ type: 'text', text: JSON.stringify(await handlers.waitForMusic(args!.taskId as string)) }] };
    // ...
  }
});

API

createHandlers(config)

Returns an object with all Suno API handlers.

interface HandlerConfig {
  apiKey: string;
  baseUrl: string;
  maxPollAttempts?: number; // default: 30
  pollIntervalMs?: number;  // default: 10000
}

Returned handlers:

| Handler | Description | |---------|-------------| | generateMusic(params) | Start generation, returns { taskId, status, message } | | getMusicStatus(taskId) | Check status, returns tracks on SUCCESS | | waitForMusic(taskId) | Poll until SUCCESS or terminal error | | listRecentMusic(page, limit) | List recent generations | | getCredits() | Get remaining credits |

toolSchemas

Array of MCP-compatible tool definitions (name, description, inputSchema) ready to pass to ListToolsRequestSchema handler. Includes all 5 tools with full JSON Schema validation.

Supported models

V4 · V4_5 · V4_5PLUS · V4_5ALL · V5 · V5_5

Key behavior

• Simple mode (customMode: false): style and title are NOT sent to the API — Suno generates them automatically from prompt
• Custom mode (customMode: true): prompt is used as literal lyrics, style and title are sent
• vocalGender is only sent when instrumental: false
• Terminal errors (SENSITIVE_WORD_ERROR, GENERATE_AUDIO_FAILED, CREATE_TASK_FAILED, CALLBACK_EXCEPTION) cause waitForMusic to throw immediately

Development

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

License

MIT © YellowKode Academy · Wunka Tech