Musicboxmelodies

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Compose, save and print music box tunes for 15, 20 and 30-note music boxes.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "Musicboxmelodies": {
      "url": "https://api.musicboxmelodies.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (17)

• list_music_boxes read-only

  Lists the music box types a melody can be written for, with their exact playable notes and rules. Call this before composing or validating a melody.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• search_songs read-only

  Searches the public catalog of music box tunes made by the Musicboxmelodies community. Search by song name, artist or arranger; optionally only tunes that have a version for one box type. Returns at most 20 per page.

  Parameters:

  • box — string — Only tunes with a version for this box.
  • page — integer — Page number, starting at 1.
  • query — string — Words to search in the song name, artist or arranger. Omit to list tunes.
  • page_size — integer — Results per page, 1-20 (default 10).

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• get_song read-only

  Gets a music box tune with its notes in the melody format (the same one validate_melody accepts), for one box version. Works for public tunes, for the signed-in person's own songs, and for a song this agent saved anonymously (pass its claim_token). Use search_songs or list_my_songs to find song ids.

  Parameters:

  • song_id (required) — string — Song id from search_songs, list_my_songs or create_song.
  • box — string — Which version to return. Defaults to the version the arranger marked as preferred.
  • claim_token — string — Only for songs saved without an account: the claim_token create_song returned.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• validate_melody read-only

  Checks whether a melody can be played on a music box: notes outside the box, same note repeated too fast, off-grid notes, tempo and length. Every issue names the note and how to fix it. Saves nothing. Call it before offering a melody to the person.

  Parameters:

  • box (required) — string — Music box type: "15", "20", "30" (notes) or "freestyle" (digital only). See list_music_boxes.
  • bpm (required) — number — Tempo in beats per minute (30-300).
  • notes (required) — array — Notes in any order, at most 2000. Only onsets matter: music boxes have no note durations.
  • snap_beats — number — Optional grid in beats (e.g. 0.5) to warn about notes off that grid.
  • illegal_threshold_ticks — integer — Minimum gap between two identical notes, in ticks (default 384 = 2 beats).

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• fit_melody_to_box read-only

  Adjusts a melody so it can be played on a music box and lists every change. Strategies: "transpose" (shift the whole melody to the key that fits best), "nearest_note" (move each unplayable note to the closest playable one), "transpose_then_nearest" (default: both). Optionally snaps notes to a grid. Returns the new melody and its validation.

  Parameters:

  • box (required) — string — Music box type: "15", "20", "30" (notes) or "freestyle" (digital only). See list_music_boxes.
  • bpm (required) — number — Tempo in beats per minute (30-300).
  • notes (required) — array — Notes in any order, at most 2000. Only onsets matter: music boxes have no note durations.
  • strategy — string
  • target_box — string — Box to fit into. Defaults to the melody's box.
  • quantize_beats — number — Snap every note to this grid in beats (e.g. 0.5 = eighth notes).
  • illegal_threshold_ticks — integer — Minimum gap between two identical notes, in ticks (default 384 = 2 beats).

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• list_products read-only

  Lists what Musicboxmelodies sells, with current prices in US dollars and delivery times: custom music box melodies, custom printable strip designs and PRO composer accounts. Orders are placed and paid by the person on the website.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• create_song

  Saves a melody as a new private song. The melody must have no errors (run validate_melody or fit_melody_to_box first); warnings such as notes repeated too quickly are saved and marked, as in the composer. If the person is signed in, the song goes to their account and you get a link to open it in the composer. Without an account the song is saved anonymously and you get a claim link: give it to the person so they can keep it (valid 30 days). Set save_to_my_account to true to ask the person to sign in first (apps that cannot sign in mid-conversation should save without an account and give the claim link instead). Limits: 5 songs a day without an account, 15 a day with one.

  Parameters:

  • name (required) — string — Song title.
  • artist (required) — string — Original artist or composer ("Traditional" if unknown).
  • box (required) — string — Music box type: "15", "20", "30" (notes) or "freestyle" (digital only). See list_music_boxes.
  • bpm (required) — number — Tempo in beats per minute (30-300).
  • notes (required) — array — Notes in any order, at most 2000. Only onsets matter: music boxes have no note durations.
  • tags — array
  • description — string — Optional notes about the arrangement.
  • save_to_my_account — boolean — True to save it in the person's account; they will be asked to sign in if they are not.
  • illegal_threshold_ticks — integer — Minimum gap between two identical notes, in ticks (default 384 = 2 beats).

  Hints: read-only no · destructive no · idempotent no · open-world no

• add_version destructive

  Saves a melody as the version of an existing song for one box (a song can have one version per box: 15, 20, 30 notes or freestyle). Replaces that box's version if it exists. Works on the signed-in person's songs, or on a song saved without an account if you pass its claim_token. The melody must have no errors.

  Parameters:

  • song_id (required) — string
  • box (required) — string — Music box type: "15", "20", "30" (notes) or "freestyle" (digital only). See list_music_boxes.
  • bpm (required) — number — Tempo in beats per minute (30-300).
  • notes (required) — array — Notes in any order, at most 2000. Only onsets matter: music boxes have no note durations.
  • claim_token — string — Only for songs saved without an account.
  • illegal_threshold_ticks — integer — Minimum gap between two identical notes, in ticks (default 384 = 2 beats).

  Hints: read-only no · destructive yes · idempotent yes · open-world no

• list_my_songs read-only

  Lists the signed-in person's songs on Musicboxmelodies, newest first, including private ones. Requires signing in.

  Parameters:

  • page — integer
  • page_size — integer — Default 20.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• set_song_visibility

  Makes one of the signed-in person's songs public (anyone can find and play it on musicboxmelodies.com) or private. Only make a song public when the person asked for it: ask them to confirm, then call again with confirmed: true.

  Parameters:

  • song_id (required) — string
  • visibility (required) — string
  • confirmed — boolean — Required to make a song public: true only after the person confirmed.

  Hints: read-only no · destructive no · idempotent yes · open-world yes

• delete_song destructive

  Permanently deletes one of the signed-in person's songs (all its box versions), or a song you saved without an account (pass its claim_token). This cannot be undone: tell the person which song will be deleted, ask them to confirm, then call again with confirmed: true.

  Parameters:

  • song_id (required) — string
  • confirmed — boolean — true only after the person confirmed the deletion.
  • claim_token — string — Only for songs saved without an account.

  Hints: read-only no · destructive yes · idempotent yes · open-world no

• export_song read-only

  Creates a download link for one box version of a song: an MP3, a MIDI file or a printable strip PDF to cut and punch for a hand-crank music box ("pdf_long" is one continuous strip, "pdf_a4"/"pdf_letter" are sliced to fit the page). Works on the person's songs and on public tunes. Requires signing in, like exporting in the composer.

  Parameters:

  • song_id (required) — string
  • format (required) — string
  • box — string — Which version. Defaults to the preferred one.
  • grid — string — Grid printed on the strip (PDF only). Default standard.
  • show_title — boolean — Print the song title on the strip (PDF only). Default true.
  • strip_shape — string — Shape of the strip ends (PDF only). Default capped.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• render_audio read-only

  Creates an MP3 of a melody (before or without saving it) or of a saved song, so you and the person can hear it. Pass either song_id or a melody (box, bpm, notes). Sounds: "synth" (free, the site's default sound) or "music_box" (real music box recordings for the box; PRO accounts only). Saved songs use the sound their author chose unless you pass one. Up to 5 minutes; 20 new audios a day without an account and 60 with one (the same melody again is free).

  Parameters:

  • box — string — With song_id: which version. Otherwise the melody's box.
  • bpm — number — Melody tempo (required without song_id).
  • notes — array — Melody notes (required without song_id).
  • sound — string
  • song_id — string — A saved song (public, the person's own, or one you saved without an account with its claim_token).
  • claim_token — string
  • illegal_threshold_ticks — integer — Minimum gap between two identical notes, in ticks (default 384 = 2 beats).

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• import_midi read-only

  Converts a MIDI file (base64, up to 512 KB) into the melody format and validates it for a box, so you can fit, edit and save it. Drums are ignored. Saves nothing.

  Parameters:

  • midi_base64 (required) — string — The .mid file, base64-encoded.
  • box — string — Box to validate against. Default "30".

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• get_product_options read-only

  Lists the variations (with prices in US dollars) and the details needed to order a custom music box melody or a custom strip design. Call it before prepare_order.

  Parameters:

  • product (required) — string — "custom_melody" (a song arranged in music box style, delivered as audio) or "custom_strip_design" (printable strips for a 15 or 30-note hand-crank box).

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

• prepare_order

  Prepares a custom melody or strip design order with all its details and returns a link to the Musicboxmelodies cart, where the person reviews it, adds photos if needed, applies discount codes and pays with PayPal. Nothing is charged here. The link works for 7 days. Confirm the song, the variation and the price with the person before calling it. The price is calculated by the site.

  Parameters:

  • product (required) — string — "custom_melody" (a song arranged in music box style, delivered as audio) or "custom_strip_design" (printable strips for a 15 or 30-note hand-crank box).
  • variation_id (required) — string — From get_product_options.
  • song_name (required) — string
  • song_artist (required) — string
  • time (required) — string — Part of the song to convert, e.g. "0:00 - 1:30" or "whole song".
  • theme — string — Strip designs only.
  • note_count — Strip designs only: notes of the person's music box.
  • existing_tune — boolean — Strip designs only: the song is already on our YouTube channel (25% off).
  • reference_link — string — YouTube or other link to the version the person wants.

  Hints: read-only no · destructive no · idempotent no · open-world yes

• get_order_status read-only

  Shows the signed-in person's orders (newest first) or one order: its status, items, price and, once delivered, the links to the finished files. Requires signing in.

  Parameters:

  • order_id — string — Omit to list recent orders.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world no

Publisher website

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.