About tunova
tunova is an SDK and hosted MCP service for generating Suno AI music, aimed at developers and MCP clients. It supports v5.5, asynchronous jobs, and billing only when generation succeeds.
Key features
- 01Generate music with Suno v5.5
- 02Python and Node/TypeScript SDKs
- 03Submit jobs and poll results
- 04Callback URLs and signed webhooks
- 05No charge for failed jobs
Use cases
- 01Generate tracks from an MCP client
- 02Call music generation from Python or Node projects
- 03Receive asynchronous job results through webhooks
MCP support
The hosted Streamable HTTP MCP service provides generate_song, wait_for_song, and check_song tools, using a Tunova API key.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://api.tunova.ai/mcpclaude mcp add --transport http erliona-tunova https://api.tunova.ai/mcp{"mcpServers":{"erliona-tunova":{"type":"http","url":"https://api.tunova.ai/mcp"}}}Open in Cursor{"servers":{"erliona-tunova":{"type":"http","url":"https://api.tunova.ai/mcp"}}}Open in VS Code{"mcpServers":{"erliona-tunova":{"type":"http","url":"https://api.tunova.ai/mcp"}}}{"mcpServers":{"erliona-tunova":{"serverUrl":"https://api.tunova.ai/mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
https://api.tunova.ai/mcpAuth requiredTools
3| Parameter | Type | Required | Description |
|---|---|---|---|
| tags | string | No | Style/genre, e.g. 'lofi hip hop, mellow, rainy'. Most useful in custom mode. |
| model | enum | No | Suno model: v6, or v5.5 as a compatibility alias for v6. Optional; the account default is unchanged.v6 | v5.5 |
| title | string | No | Song title (custom mode). |
| custom | boolean | No | false (default): describe the song and Suno writes everything. true: `prompt` is the literal lyrics, and `tags`/`title` are used. |
| prompt | string | Yes | What the song should be about (simple mode), or the exact lyrics (when custom=true). |
| instrumental | boolean | No | If true, generate without vocals. |
| idempotency_key | string | No | Optional logical-request id. Reuse it to recover one submit; use a new value to intentionally generate the same song again or retry after a terminal failed job. When omitted, Tunova derives a stable key from the song arguments for safe automatic retries. |
Details
From the project READMETunova SDK
Tiny, zero-dependency clients + MCP manifest for the Tunova music API — generate music with Suno (v5.5) over a simple REST or MCP interface. Generation is async and billed only on success: a failed render refunds itself.
- Python →
python/tunova.py— stdlib only, Python 3.8+. - Node / TypeScript →
node/tunova.ts— Node 18+ (fetchbuilt in). - MCP →
server.json— hosted Streamable-HTTP server athttps://api.tunova.ai/mcp.
Get a key (50 free tokens, no card) at https://tunova.ai. Full reference: https://api.tunova.ai/docs · live status: https://tunova.ai/status.
Tunova is an independent service, not affiliated with or endorsed by Suno. Tracks come from paid Suno plans; review Suno's terms for your use case.
Python
pip install tunova
from tunova import Tunova
t = Tunova("sk_live_…")
job = t.generate("warm lo-fi piano to study to", model="v5.5")
print(job["clips"][0]["audio_url"] if job["status"] == "complete" else job["error"])
Prefer no install? python/tunova.py is stdlib-only — vendor the single file and import it.
Node / TypeScript
npm i tunova
import { Tunova } from "tunova";
const t = new Tunova(process.env.TUNOVA_API_KEY!);
const job = await t.generate("warm lo-fi piano to study to", { model: "v5.5" });
console.log(job.status === "complete" ? job.clips[0]?.audio_url : job.error);
Both generate() calls submit a job and poll until the track is delivered. Prefer fire-and-forget?
Use submit() with a callback_url and take an HMAC-signed webhook instead.
MCP — give an AI agent the power to make music
claude mcp add --transport http tunova https://api.tunova.ai/mcp \
--header "X-API-Key: sk_live_…"
Tools: generate_song · wait_for_song · check_song. Same API key, same billed-on-success rule.
Verifying webhooks
If you pass callback_url, Tunova POSTs the terminal job with
X-Webhook-Signature: sha256=<hmac> over <X-Webhook-Timestamp>.<rawBody>, keyed with your
whsec_… secret (view/rotate it on the dashboard's API-keys page). Verify against the raw body
before parsing — both SDKs ship a verifier (Tunova.verify_webhook / verifyWebhook).
License
MIT — see LICENSE. The SDK code is yours to use freely; your use of the Tunova API is governed by the terms.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.