tuxguitar-claude-mcp

Claude でギター/ベースのタブ譜を書けるようにするMCPサーバーです。トラック、チューニング、小節、音符、そしてパームミュート、トレモロ・ピッキング、チョーキング、ハーモニクスなどのタブ譜エフェクタを、TuxGuitarで開ける .gp5 ファイルとして直接書き出します。

これはフェーズ1であり、ファイルベースのみです。実行中のTuxGuitarインスタンスをライブ制御する機能はありません（それ tは将来のフェーズ2として予定されており、まだ設計されていません）。

しくみ

MCPサーバー（TypeScript、@modelcontextuo/sdk）は、Claude がツール呼び出しごとに構築するインメモリの楽曲状態を保ホしル。トラックの作成、小節の追加、チューニングの設定、ビートと音符の挿入など行います。save_song は、その状態を小型の Java ヘルパー（song-writter/、TuxGuitar のライブラリ自体を使ってビルド）に渡し、実際の .gp5 ファイルにシリアライズします。

必要条件

• Windows かつ TuxGuitarがインストールされていること。サーバーは、そのインストールに同梡される JRE（jre\bin\java.exe）および TuxGuitar 自身のライブラリにワーーアウトし、有効な .gp5 ファイルを書きます。TuxGuitar 自体は実効されている必要はありません。デフォルトは C:\Program Files\tuxguitar です。別の場所にインストールしている場合は、T UXGUDITAR_HOME 環境変数で上書きしてください。

• Node.js（18+）: MCP サーバー用。

• Java 21 : Java ヘルパーを一度ビルドするために必要です（例: Eclipse Temurin JDK 21）。実行時には不要です。実行時は TuxGuitar に同梱された JRE が使用されます。

• Claude Code（または他の MCP 互換クライアント）でサーバーを登録して使用します。

セットアップ

1. Java song-writer をビルドする

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

任意で、テストを実行します:

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

2. MCP サーバーをビルドする

npm install
npm run build
npm run test

3. Claude Code に登録する

mcpServers に追加します（グローバルでは ~/.claude.json、プロジェクトでは .mcp.json）:

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

TuxGuitar が C:\Program Files\tuxguitar にインストールされていない場合は、env で TUXGUITAR_HOME を設定してください:

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

新しいサーバーを認識させるため、Claude Code を再起動してください。

ツール

手動統合テスト

1. tuxguitar_ping を呼び出し、"ok" が返ることを期待します。

2. new_song、create_track、add_measure、add_beats、save_song を順に呼び出します。

3. 結 pow果の .gp5 ファイルを実際の TuxGuitar アプリで開き、視覚的/聴覚的に確認します。

既知の制限

• フェーズ1のみ: 実行中の TuxGuitar インスタンスをライブ制御できません。

• add_beats は、ビートが小節の合計長に収まるかどうかを検証しません。超過してもエラーになりません。 *ビートのな小節は非整で、縵0は本当に空ですが、それ以イ後の小節には TuxGuitar の自動入された休符ビートが残ります。

• Windows のみ対応。

トラブルシューテング

• "Unknown track_id" / "Unknown measure_index": 呼び出しの順序を確認してください。add_beats がそれらを参照する前に、トラックと小節が存在している必要があります。

• tuxguitar_pingが失敗した場合: song-writer\dist\tuxguitar-song-writer.jar が存在するか（build.ps1 を再実行）を確認し、TUXGUITAR_HOME（またはデフォルトの C:\Program Files\tuxguitar）が実際の TuxGuitar インストールを指していルるか確認してください。

ライセンス

MIT