吉他专家MCP
项目介绍
Guitar Pro MCP Server
这是一个用于操作Guitar Pro文件的消息控制协议（MCP）服务器。该服务器提供了一组工具，通过标准化接口来打开、修改和保存Guitar Pro文件。
注意：目前仅测试了Guitar Pro 5（.gp5）格式。对其他格式（.gp3, .gp4）的支持可能有限或未经测试。
功能
- 加载和保存Guitar Pro文件
- 获取歌曲信息（标题、艺术家、轨道等）
- 从轨道中提取音符
- 创建新歌曲并添加轨道
- 操作轨道属性
- 导出为MIDI格式
- 导入/导出为JSON格式
要求
- Python 3.10或更高版本
- PyGuitarPro库
- MCP服务器框架
- MIDI支持（mido库）
- uv（推荐用于包管理）
安装
使用uv（推荐）
- 如果尚未安装，请安装uv：
pip install uv
- 创建并激活虚拟环境：
# 创建虚拟环境
uv venv
# 激活虚拟环境
# 在Unix/macOS上：
source .venv/bin/activate
# 在Windows(cmd)上：
call .venv\Scripts\activate.bat
- 安装包：
uv pip install .
运行服务器
你可以使用uv直接运行服务器：
uv --directory <项目路径> run -m src.run_mcp_server
例如，在Windows上：
uv --directory C:\path\to\guitar_pro_mcp2 run -m src.run_mcp_server
或者在安装后直接使用Python模块：
python -m src.run_mcp_server
使用pip
pip install guitar-pro-mcp
从源代码
- 克隆仓库：
git clone https://github.com/yourusername/guitar-pro-mcp.git
cd guitar-pro-mcp
- 安装包：
# 开发模式安装所有依赖项
pip install -e ".[dev]"
# 或者不带开发依赖项安装
pip install -e .
- 使用MCP客户端连接到服务器。
使用方法（直接）
- 启动MCP服务器：
python src/run_mcp_server.py
- 使用MCP客户端连接到服务器。
可用的MCP工具
文件操作
-
load_guitar_pro: 加载一个Guitar Pro文件- 参数：
file_path（指向.gp5文件的路径） - 返回值：成功/错误消息
- 参数：
-
save_guitar_pro: 将当前歌曲保存为Guitar Pro文件- 参数：
file_path（保存文件的路径） - 返回值：成功/错误消息
- 参数：
歌曲信息
-
get_song_info: 获取当前加载歌曲的基本信息- 返回值：包含标题、艺术家、专辑、版权、副标题、通知和轨道数量的字典
-
get_song_statistics: 获取当前歌曲的详细统计信息- 返回值：包含轨道数量、小节数量、音符数量和详细的轨道信息的字典
轨道操作
-
get_gp_tracks: 获取当前Guitar Pro歌曲中的轨道列表- 返回值：包含每个轨道名称、索引、弦数和乐器的轨道列表
-
get_track_notes: 获取特定轨道的所有音符- 参数：
track_index（轨道索引） - 返回值：包含音符属性（小节、拍子、弦、值等）的音符列表
- 参数：
-
add_gp_track: 向Guitar Pro歌曲添加新的轨道- 参数：
name（轨道名称） - 返回值：成功消息和轨道索引
- 参数：
-
set_track_properties: 设置轨道属性- 参数：
track_index: 轨道索引name: 新轨道名称（可选）instrument: 乐器ID（可选）volume: 音量级别（可选）pan: 声像位置（可选）
- 返回值：成功/错误消息
- 参数：
小节操作
-
add_gp_measure: 向Guitar Pro歌曲添加新的小节- 返回值：成功消息和小节索引
-
set_gp_time_signature: 设置小节的时间签名- 参数：
measure_index,numerator,denominator - 返回值：成功/错误消息
- 参数：
-
set_gp_key_signature: 设置小节的关键签名 、参数：measure_index,key- 返回值：成功/错误消息
-
set_gp_tempo: 设置小节的速度- 参数：
measure_index,tempo - 返回值：成功/错误消息
- 参数：
音符操作
add_gp_note: 向特定轨道和小节添加音符- 参数：
track_index: 轨道索引measure_index: 小节索引string: 弦号fret: 品位号duration: 音符时长（默认：4）voice_index: 声部索引（默认：0）beat_index: 拍子索引（默认：0）
- 返回值：成功/错误消息
- 参数：
导入/导出操作
-
export_to_midi: 将当前歌曲导出为MIDI格式- 参数：
file_path - 返回值：成功/错误消息
- 参数：
-
export_to_json: 将当前歌曲导出为JSON格式- 参数：
file_path - 返回值：成功/错误消息
- 参数：
-
import_from_json: 从JSON格式导入歌曲- 参数：
file_path - 返回值：成功/错误消息
- 参数：
Tab操作
get_track_tab: 生成轨道的ASCII Tab表示- 参数：
track_index - 返回值：作为字符串的ASCII Tab表示
- 参数：
歌曲结构管理
-
add_repeat_group: 向歌曲添加重复组- 参数：
start_measure: 起始小节索引end_measure: 结束小节索引repeat_type: 重复类型（"normal", "alternate", "repeat_1st", "repeat_2nd"）repeat_count: 重复次数（默认：2）endings: 结尾数字列表（可选）
- 返回值：成功/错误消息
- 参数：
-
get_repeat_groups: 获取歌曲中的所有重复组- 返回值：包含重复组对象及其属性的列表
-
add_section: 向歌曲添加部分- 参数：
start_measure: 起始小节索引end_measure: 结束小节索引name: 部分名称text: 可选部分文本color: 可选部分颜色作为RGB元组
- 返回值：成功/错误消息
- 参数：
-
get_sections: 获取歌曲中的所有部分- 返回值：包含部分对象及其属性的列表
-
add_coda: 向小节添加coda标记- 参数：
measure_index - 返回值：成功/错误消息
- 参数：
-
add_double_bar: 向小节添加双竖线- 参数：
measure_index - 返回值：成功/错误消息
- 参数：
-
get_song_structure: 获取完整的歌曲结构- 返回值：包含以下内容的字典：
sections: 所有部分的列表repeat_groups: 所有重复组的列表markers: 所有标记（coda、双竖线等）的列表
- 返回值：包含以下内容的字典：
元数据和歌词
-
set_lyrics: 设置当前歌曲的歌词- 参数：
lyrics（包含歌词的字符串） - 返回值：成功/错误消息
- 参数：
-
get_lyrics: 获取当前歌曲的歌词- 返回值：作为字符串的歌词
-
set_page_setup: 设置当前歌曲的页面设置- 参数：
page_setup（包含页面设置属性的字典） - 属性包括：pageSize, pageMargin, scoreSizeProportion, headerAndFooter, title, subtitle, artist, album, words, music, wordsAndMusic, copyright, pageNumber
- 返回值：成功/错误消息
- 参数：
-
get_page_setup: 获取当前歌曲的页面设置- 返回值：包含页面设置属性的字典
-
set_advanced_metadata: 设置当前歌曲的高级元数据- 参数：
metadata（包含元数据属性的字典） - 属性包括：subtitle, words, music, tab, instructions, notice
- 返回值：成功/错误消息
- 参数：
-
get_advanced_metadata: 获取当前歌曲的高级元数据- 返回值：包含元数据属性的字典
和弦操作
-
add_chord: 向特定拍子添加和弦- 参数：
track_index: 轨道索引measure_index: 小节索引beat_index: 拍子索引chord_data: 包含和弦属性的字典
- 和弦属性包括：name, root, type, extension, bass, tonality, fifth, ninth, eleventh, firstFret, strings, barres, fingerings
- 返回值：成功/错误消息
- 参数：
-
get_chord: 获取特定拍子的和弦- 参数：
track_index: 轨道索引measure_index: 小节索引beat_index: 拍子索引
- 返回值：包含和弦属性的字典
- 参数：
Claude配置（使用uv run）：
{
"mcpServers": {
"guitar-pro-mcp": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"<文件夹路径>",
"run",
"-m",
"src.run_mcp_server"
]
}
}
}
Claude配置（直接使用）：
{
"mcpServers": {
"guitar-pro-mcp": {
"type": "stdio",
"command": "python",
"args": [
"<文件夹路径>\\src\\run_mcp_server.py"
]
}
}
}
Claude配置（使用uv run）：
{
"mcpServers": {
"guitar-pro-mcp": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"<文件夹路径>",
"run",
"-m",
"src.run_mcp_server"
]
}
}
}
实现细节
实现使用PyGuitarPro库解析和操作Guitar Pro文件。MCP服务器提供了一个简单的API来访问PyGuitarPro库的功能。
许可证
本项目根据MIT许可证授权。