tuxguitar-claude-mcp

一个 MCP 服务器，通过 Claude 可以直接编写吉他/贝斯六线谱——音轨、调弦、小节、效果、音符——比如弦音、闷音、颤音吉他、推弦和泛音——并另存为 TuxGuitar 能打开的 .gp5 文件。

这是阶段 1：仅支持文件基于级，不控制 TuxGuitar 实例的实时运行（那将留到未来的阶段 2，尚未设计）。

如何工作

MCP 服务器（TypeScript，@modelcontextprotocol/sdk）在内存中维护歌曲状态，Claude通过一次一次的调用构建它——可以创建音轨、添加小节、设置调弦、插入节拍与音符。save_song 把这个状态交给一个小型 Java 辅助程序（song-writer/，它基于 TuxGuitar 的库构建），再序列化为真正 .gp5 文件。

要求

• Windows，并已安装 TuxGuitar 。安装服务器会调用随该安装一起使用的 JRE（jre\bin\java.exe）与安装了 TuxGuitar 自己的要用的类来写有效的 .gp5 文件，而 TuxGuitar 自身不需要正在运行。如果需要，可在 TUXGUITAR_HOME 环境变量中覆盖默认安装目录 C:\Program Files\tuxguitar。若你安装在别的位置，则设置 TUXGUITAR_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 中注册

在 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. 使用真实 TuxGuitar 应用打开生成的 .gp5 文件，并从视觉/听觉上检查它。

已知限制

• 仅阶段 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