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

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