{"name":"suno-mcp","version":"0.2.0","transport":"Streamable HTTP","endpoint":"/mcp","tools":[{"name":"search","description":"Search Suno for songs by free-text term, with optional filters. Returns LEAN previews only (id, title, handle, image_url, audio_url to play, duration, model, a short style, and a lyrics_excerpt) — NOT full lyrics, to keep results small. For the complete details of one result (full lyrics, all fields) call get_clip with its id. Use next_cursor for the next page. Results are cached so get_clip / import / playlist tools can reuse them.","inputSchema":{"type":"object","properties":{"q":{"type":"string","description":"search term"},"rank":{"type":"string","description":"ranking: 'trending' (default), 'most_relevant', 'most_recent', etc."},"models":{"type":"string","description":"filter by model version(s), comma-separated (e.g. 'chirp-v4')."},"langs":{"type":"string","description":"filter by language(s), comma-separated."},"creators":{"type":"string","description":"filter by creator handle(s), comma-separated."},"page_size":{"type":"integer","minimum":1,"maximum":50,"default":20},"cursor":{"type":"string","default":"0","description":"pagination cursor; pass the previous next_cursor."}},"required":["q"]}},{"name":"search_by_tag","description":"Radio-style search by a single style/genre tag (e.g. 'lofi', 'gnawa', 'phonk'). Returns lean previews like search, plus total_hits and the page index. Use the `page` param to paginate. Call get_clip(id) for full details of a result.","inputSchema":{"type":"object","properties":{"q":{"type":"string","description":"the style tag to search by"},"rank":{"type":"string","description":"ranking, default 'most_relevant'."},"page":{"type":"integer","minimum":0,"default":0,"description":"page index (0-based)."}},"required":["q"]}},{"name":"get_clip","description":"Fetch ONE Suno clip's FULL details by id — complete lyrics, style, model, audio_url, image_url, video_url, duration. This is the 'expand for details' call to use after search / search_by_tag / get_user_clips / get_similar (which return lean previews only).","inputSchema":{"type":"object","properties":{"id":{"type":"string","description":"Suno clip uuid"}},"required":["id"]}},{"name":"get_user_clips","description":"List recent clips for a Suno creator handle (lean previews; use get_clip for full details).","inputSchema":{"type":"object","properties":{"handle":{"type":"string","description":"Suno user handle (no @)"}},"required":["handle"]}},{"name":"get_similar","description":"Get clips similar to a given clip id (lean previews; use get_clip for full details).","inputSchema":{"type":"object","properties":{"id":{"type":"string"},"count":{"type":"integer","minimum":1,"maximum":50,"default":20}},"required":["id"]}},{"name":"generate_song","description":"Create ONE song on Suno. IMPORTANT — there are two distinct, mutually-exclusive ways to supply content, do not mix them:\n  • lyrics  = the EXACT words to be sung, verbatim (verses/chorus, any language). Use this when you already have the song text. Put ONLY the words here — never instructions like 'write a song about…'.\n  • description = a short brief (e.g. 'an upbeat lo-fi song about a sunny afternoon'); Suno writes the lyrics itself. Use this when the user gives an idea, not actual words.\nProvide lyrics OR description, not both. `style` is the musical style/genre tags. Returns clip ids (each call usually yields 2 takes) and caches them for playlist/cover/import tools.","inputSchema":{"type":"object","properties":{"lyrics":{"type":"string","description":"The literal words to sing, verbatim. NOT a directive."},"description":{"type":"string","description":"A short brief; Suno writes the lyrics from it. Use instead of lyrics."},"style":{"type":"string","description":"Style/genre tags, comma-separated (e.g. 'lo-fi, chill, piano')."},"title":{"type":"string"},"instrumental":{"type":"boolean","default":false,"description":"No vocals if true; lyrics are ignored."},"model":{"type":"string","description":"Model version, default chirp-fenix."}}}},{"name":"generate_songs_bulk","description":"Create MANY songs in one request (up to 10). Pass `songs` as an array where each item has the same shape as generate_song (lyrics OR description, style, title, instrumental, model). Each is submitted sequentially with a small delay (`stagger_ms`, default 2000) between them to avoid hammering Suno. Returns one result per song with its clip ids. Songs that fail are reported with an error instead of aborting the whole batch.","inputSchema":{"type":"object","properties":{"songs":{"type":"array","minItems":1,"maxItems":10,"description":"Array of song specs (max 10).","items":{"type":"object","properties":{"lyrics":{"type":"string","description":"Literal words to sing. NOT a directive."},"description":{"type":"string","description":"Brief; Suno writes lyrics from it. Use instead of lyrics."},"style":{"type":"string","description":"Style/genre tags."},"title":{"type":"string"},"instrumental":{"type":"boolean","default":false},"model":{"type":"string"}}}},"stagger_ms":{"type":"integer","minimum":0,"maximum":30000,"default":2000,"description":"Delay between consecutive submissions (ms)."}},"required":["songs"]}},{"name":"create_cover","description":"COVER an existing Suno clip — re-record the SAME song (keeps its melody/structure) in a new style. This is NOT generate_song: it is conditioned on a source clip. Give the source `clip_id`; leave `lyrics` empty to keep the original words, or pass replacement `lyrics`. The result's metadata carries task='cover' and cover_clip_id=<clip_id>. Caches the clips.","inputSchema":{"type":"object","properties":{"clip_id":{"type":"string","description":"Source Suno clip id to cover (required)."},"style":{"type":"string","description":"New style/genre tags for the cover."},"title":{"type":"string"},"lyrics":{"type":"string","description":"Optional replacement lyrics; empty = keep source's."},"instrumental":{"type":"boolean","default":false},"model":{"type":"string","description":"Model version, default chirp-fenix."}},"required":["clip_id"]}},{"name":"create_sample","description":"SAMPLE / 'inspired by' an existing Suno clip — generate a NEW song that chops/samples the source as its musical seed (looser than a cover). Conditioned on the source, NOT a fresh generate. Give the source `clip_id` plus optional `style`, `title`, `lyrics`, `model`. Result metadata carries task='chop_sample_condition' and chop_sample_clip_id=<clip_id>.","inputSchema":{"type":"object","properties":{"clip_id":{"type":"string","description":"Source Suno clip id to sample (required)."},"style":{"type":"string","description":"Style/genre tags for the new track."},"title":{"type":"string"},"lyrics":{"type":"string","description":"Optional lyrics (verbatim words)."},"instrumental":{"type":"boolean","default":false},"model":{"type":"string","description":"Model version, default chirp-fenix."}},"required":["clip_id"]}},{"name":"create_mashup","description":"MASHUP two (or more) existing Suno clips into one new track. Conditioned on the source clips, NOT a fresh generate. Pass `clip_ids` (the source ids to blend) plus optional `style`, `title`, `lyrics`, `model`. Result metadata carries task='mashup_condition' and mashup_clip_ids=<clip_ids>.","inputSchema":{"type":"object","properties":{"clip_ids":{"type":"array","items":{"type":"string"},"minItems":2,"description":"Source clip ids to mash up (at least 2)."},"style":{"type":"string","description":"Style/genre tags for the mashup."},"title":{"type":"string"},"lyrics":{"type":"string","description":"Optional lyrics (verbatim words)."},"instrumental":{"type":"boolean","default":false},"model":{"type":"string","description":"Model version, default chirp-fenix."}},"required":["clip_ids"]}},{"name":"check_clips","description":"Check the status/metadata of generated clips by id (use after generate_song / generate_songs_bulk to see when they finish). Accepts up to ~20 ids. Returns id, title, status, duration and audio/image urls; refreshes the local cache.","inputSchema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":20}},"required":["ids"]}},{"name":"improve_tags","description":"Have Suno's AI rewrite a style/genre tag string into something richer.","inputSchema":{"type":"object","properties":{"tags":{"type":"string","description":"Style/genre tags to improve."},"is_instrumental":{"type":"boolean","default":false}},"required":["tags"]}},{"name":"write_lyrics","description":"Have Suno's AI write lyrics from an idea. Returns suggested lyrics text you can then feed into generate_song's `lyrics` field. This does NOT create a song by itself.","inputSchema":{"type":"object","properties":{"about":{"type":"string","description":"What the song should be about (the idea/theme)."},"title":{"type":"string"}},"required":["about"]}},{"name":"list_my_playlists","description":"List your own Suno playlists (paginated).","inputSchema":{"type":"object","properties":{"page":{"type":"integer","minimum":1,"default":1}}}},{"name":"get_playlist","description":"Get a playlist (and its clips) by id.","inputSchema":{"type":"object","properties":{"id":{"type":"string"},"page":{"type":"integer","minimum":1,"default":1}},"required":["id"]}},{"name":"create_playlist","description":"Create a new Suno playlist. Optionally pass `clip_ids` to immediately add those clips to it (handy right after generate_songs_bulk). Returns the new playlist's info incl. its id.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Playlist name."},"clip_ids":{"type":"array","items":{"type":"string"},"description":"Optional clips to add on creation."}},"required":["name"]}},{"name":"add_clips_to_playlist","description":"Add one or more clip ids to an existing playlist.","inputSchema":{"type":"object","properties":{"playlist_id":{"type":"string"},"clip_ids":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["playlist_id","clip_ids"]}},{"name":"remove_clips_from_playlist","description":"Remove clips from a playlist by their position indexes (0-based, as returned by get_playlist).","inputSchema":{"type":"object","properties":{"playlist_id":{"type":"string"},"indexes":{"type":"array","items":{"type":"integer"},"minItems":1}},"required":["playlist_id","indexes"]}},{"name":"import_clip","description":"Bridge: pull a Suno clip's audio (or image / video) into ffstudio uploads in one call. Looks up the URL from the cached suno_clips row (call get_clip / search first if not cached), POSTs to ffstudio /upload/url with source='suno' + source_ref=<clip_id>, and records the import in suno_imports. Returns the new ffstudio file_id ready for run_recipe.","inputSchema":{"type":"object","properties":{"clip_id":{"type":"string","description":"Suno clip id (must be cached or fetched first)"},"asset":{"type":"string","enum":["audio","image","video"],"default":"audio"}},"required":["clip_id"]}},{"name":"list_cached_clips","description":"List Suno clips this MCP has cached (in the shared SQLite). Cheap discovery without hitting Suno. Use this to remind yourself what the agent has already touched in this workspace.","inputSchema":{"type":"object","properties":{"handle":{"type":"string","description":"filter by handle"},"limit":{"type":"integer","minimum":1,"maximum":200,"default":30}}}},{"name":"list_streams","description":"List streamer instances (each is one independent YouTube live channel).","inputSchema":{"type":"object","properties":{}}},{"name":"create_stream","description":"Create a new streamer instance. Returns its id; pass that id to start_stream / stop_stream.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"human-readable name"}},"required":["name"]}},{"name":"start_stream","description":"Start streaming a list of Suno clip ids to YouTube Live. clipIds is required; source picks what gets streamed: 'video' (Suno's own video), 'mp3_cover' (audio + each clip's cover), or 'mp3_static' (audio + a single static image previously uploaded via /upload-image on the instance). mode='loop' replays forever, 'once' stops after the queue. streamKey overrides the env-default RTMPS key for this run.","inputSchema":{"type":"object","properties":{"instance_id":{"type":"string"},"clipIds":{"type":"array","items":{"type":"string"},"minItems":1},"source":{"type":"string","enum":["video","mp3_cover","mp3_static"]},"mode":{"type":"string","enum":["once","loop"],"default":"loop"},"engine":{"type":"string","enum":["concat","sequential"],"default":"concat"},"streamKey":{"type":"string"},"titleOverlay":{"type":"boolean","default":false}},"required":["instance_id","clipIds","source"]}},{"name":"stop_stream","description":"Stop a running streamer instance.","inputSchema":{"type":"object","properties":{"instance_id":{"type":"string"}},"required":["instance_id"]}},{"name":"stream_status","description":"Get the full status of a streamer instance: phase, current clip, queue length, ffmpeg pid, log tail. Cheap, polls allowed.","inputSchema":{"type":"object","properties":{"instance_id":{"type":"string"}},"required":["instance_id"]}}],"usage":"claude mcp add suno --transport http <PUBLIC_URL>/mcp"}