♩Clef:

transpose_chords: move a chord chart by semitones

Move a chord chart up or down by semitones, including slash bass notes. Part of the Clef Music Tools MCP server. Endpoint: https://clefdrills.com/mcp, no account needed, read-only.

What it does

transpose_chords takes a line of chord symbols separated by spaces and returns the same chart shifted by a number of semitones. Slash chords such as G/B move both the chord root and the bass note. Sharp spelling is the default; set preferFlats to spell the result with flats.

It changes chord names only. It does not read lyrics, bar lines, audio or notation files.

Input schema

{
  "chords": string, 1 to 10000 characters, chord symbols separated by spaces
  "semitones": integer, -24 to 24
  "preferFlats": boolean, default false
}

All fields are validated before the tool runs.

Output

On success: structuredContent with chords (the transposed chart as one string) and browserTool (the matching browser tool at https://clefdrills.com/tools/chord-transposer/). The same object is also returned as JSON text in content.

Example calls

Up two semitones

curl -s https://clefdrills.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"transpose_chords","arguments":{"chords":"C G/B Am F","semitones":2}}}'

Result:

{ "chords": "D A/C# Bm G", "browserTool": "https://clefdrills.com/tools/chord-transposer/" }

Down three semitones

curl -s https://clefdrills.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"transpose_chords","arguments":{"chords":"Am F C G","semitones":-3}}}'

Result:

{ "chords": "F#m D A E", "browserTool": "https://clefdrills.com/tools/chord-transposer/" }

Flat spelling

curl -s https://clefdrills.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"transpose_chords","arguments":{"chords":"Bb Eb/G Cm7 F7","semitones":3,"preferFlats":true}}}'

Result:

{ "chords": "Db Gb/Bb Ebm7 Ab7", "browserTool": "https://clefdrills.com/tools/chord-transposer/" }

Edge cases and errors

  • Zero semitones returns the chart unchanged: {"chords":"C G","semitones":0} returns "C G".
  • preferFlats defaults to false, so C G/B Am F up two semitones with preferFlats: true returns D A/Db Bm G: the flag changes the spelling of the black-key names, so the slash bass note is written with a flat.
  • A token that is not a chord symbol makes the whole call fail with Invalid chord symbol. For example C | Xyz G (bar lines and unknown words are not accepted). Remove bar lines and section labels first.
  • semitones outside -24 to 24 is rejected before the tool runs with a validation error.

Errors come back as a normal tool result with isError: true, so the client can show the message. Real error results from the live server:

arguments: {"chords":"C | Xyz G","semitones":2}

{ "isError": true, "content": [{ "type": "text", "text": "Invalid chord symbol" }] }
arguments: {"chords":"C G","semitones":30}

{ "isError": true, "content": [{ "type": "text", "text": "MCP error -32602: Input validation error: Invalid arguments for tool transpose_chords: Number must be less than or equal to 24 at semitones" }] }

Related pages