# transpose_chords: move a chord chart by semitones

For AI agents: the site index is at https://clefdrills.com/llms.txt and the HTML version of this page is at https://clefdrills.com/docs/mcp/tools/transpose-chords.

Move a chord chart up or down by semitones, including slash bass notes. Part of the [Clef Music Tools MCP server](https://clefdrills.com/docs/mcp). 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

```bash
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:

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

### Down three semitones

```bash
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:

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

### Flat spelling

```bash
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:

```json
{ "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

- [Connect a client](https://clefdrills.com/docs/mcp/connect)
- [Limits and privacy](https://clefdrills.com/docs/mcp/limits-and-privacy)
- [All Clef Music Tools docs](https://clefdrills.com/docs/mcp)
