tuxguitar-claude-mcp

An MCP server that lets Claude write guitar/bass tabs — tracks, tuning, measures, notes, and tab effects like palm mute, tremolo picking, bends, and harmonics — directly as .gp5 files that TuxGuitar can open.

This is Phase 1: file-based only. There is no live control of a running TuxGuitar instance (that would be a future Phase 2, not yet designed).

How it works

The MCP server (TypeScript, @modelcontextprotocol/sdk) holds an in-memory song state that Claude builds up tool call by tool call — create tracks, add measures, set tuning, insert beats and notes. save_song hands that state to a small Java helper (song-writer/, built on the TuxGuitar libraries themselves) which serializes it to a real .gp5 file.

Requirements

• Windows, with TuxGuitar installed. The server shells out to the JRE bundled with that install (jre\bin\java.exe) and to TuxGuitar's own libraries to write valid .gp5 files — TuxGuitar itself does not need to be running. Defaults to C:\Program Files\tuxguitar; override with the TUXGUITAR_HOME environment variable if yours is installed elsewhere.
• Node.js (18+) for the MCP server.
• Java 21 to build the Java helper once (e.g. Eclipse Temurin JDK 21). It is not needed at runtime — TuxGuitar's bundled JRE handles that.
• Claude Code (or another MCP-compatible client) to register and use the server.

Setup

1. Build the Java song-writer

powershell -ExecutionPolicy Bypass -File song-writer\build.ps1

Optional, run its tests:

powershell -ExecutionPolicy Bypass -File song-writer\test.ps1

2. Build the MCP server

npm install
npm run build
npm run test

3. Register it with Claude Code

Add it to mcpServers in your Claude Code config (globally in ~/.claude.json, or in a project's .mcp.json):

"tuxguitar": {
  "type": "stdio",
  "command": "node",
  "args": ["<path-to-repo>\\dist\\index.js"],
  "env": {}
}

If TuxGuitar isn't installed at C:\Program Files\tuxguitar, set TUXGUITAR_HOME in env:

"env": { "TUXGUITAR_HOME": "D:\\Apps\\tuxguitar" }

Restart Claude Code so it picks up the new server.

Tools

Tool	What it does
tuxguitar_ping	Checks that Java and the song-writer helper are reachable.
new_song	Starts a new, empty song (discards current state).
set_song_info	Sets title and/or artist of the current song.
get_song	Returns the current song state as JSON.
save_song	Writes the current song state out as a .gp5 file.
create_track	Creates a new track (guitar/bass) with a tuning.
list_tracks	Lists all tracks of the current song.
set_tuning	Changes the tuning of an existing track.
add_measure	Adds a new measure at the end of the song (applies to all tracks).
set_tempo	Sets the tempo (BPM) of an existing measure.
set_time_signature	Sets the time signature of an existing measure.
add_beats	Inserts an ordered list of beats (rhythmic slots with notes) into one track's measure.
clear_measure	Removes all beats of one track in a given measure.

Manual integration test

1. Call tuxguitar_ping — expect "ok".
2. Call new_song, create_track, add_measure, add_beats, save_song in sequence.
3. Open the resulting .gp5 file in the real TuxGuitar app and check it visually/aurally.

Known limitations

• Phase 1 only: no live control of a running TuxGuitar instance.
• add_beats doesn't validate that beats fit within a measure's total length — silent overfill is accepted.
• Measures with no beats stay inconsistent: measure 0 is genuinely empty, later measures keep TuxGuitar's own auto-filled rest beat.
• Windows-only.

Troubleshooting

• "Unknown track_id" / "Unknown measure_index": check the order of calls — tracks and measures must exist before add_beats references them.
• tuxguitar_ping fails: check that song-writer\dist\tuxguitar-song-writer.jar exists (rerun build.ps1) and that TUXGUITAR_HOME (or the default C:\Program Files\tuxguitar) points at a real TuxGuitar install.

License

MIT