Guitar Pro Mcp

Guitar Pro MCP 服务

一个用于操作 Guitar Pro 文件的 Message Control Protocol（MCP）服务。该服务提供了一组工具，可通过标准化接口打开、修改和保存 Guitar Pro 文件。

注意：目前仅测试了 Guitar Pro 5（.gp5）格式。对其他格式（.gp3、.gp4）的支持可能有限或未经测试。

功能

• 加载和保存 Guitar Pro 文件
• 获取歌曲信息（标题、艺术家、音轨等）
• 从音轨中提取音符
• 创建新歌曲并添加音轨
• 操作音轨属性
• 导出为 MIDI 格式
• 导出为 JSON 格式 / 从 JSON 格式导入

环境要求

• Python 3.10 或更高版本
• PyGuitarPro 库
• MCP 服务框架
• MIDI 支持（mido 库）
• uv（推荐用于包管理）

安装

使用 uv（推荐）

1. 如果尚未安装 uv，请先安装：

pip install uv

2. 创建并激活虚拟环境：

# Create virtual environment
uv venv

# Activate virtual environment
# On Unix/macOS:
source .venv/bin/activate
# On Windows(cmd):
call .venv\Scripts\activate.bat

3. 安装该包：

uv pip install .

运行服务

你可以直接使用 uv 运行服务：

uv --directory <project_path> 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

从源码安装

1. 克隆仓库：

git clone https://github.com/yourusername/guitar-pro-mcp.git
cd guitar-pro-mcp

2. 安装该包：

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Or install without development dependencies
pip install -e .

2. 使用 MCP 客户端连接到服务。

用法（直接）

1. 启动 MCP 服务：

python src/run_mcp_server.py

2. 使用 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：向某小节添加尾声标记

  • 参数：measure_index
  • 返回：成功/错误消息

• add_double_bar：向某小节添加双小节线

  • 参数：measure_index
  • 返回：成功/错误消息

• get_song_structure：获取完整的歌曲结构

  • 返回：包含以下内容的字典：
    • sections：所有段落的列表
    • repeat_groups：所有重复组的列表
    • markers：所有标记（尾声、双小节线等）的列表

元数据与歌词

• 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",
                "<path to folder>",
                "run",
                "-m",
                "src.run_mcp_server"
            ]
        }
    }
}

Claude 配置（直接使用）：

{
    "mcpServers": {
        "guitar-pro-mcp": {
            "type": "stdio",
            "command": "python",
            "args": [
                "<path to folder>\\src\\run_mcp_server.py"
            ]
        }
    }
}

Claude 配置（使用 uv run）：

{
    "mcpServers": {
        "guitar-pro-mcp": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "--directory",
                "<path to folder>",
                "run",
                "-m",
                "src.run_mcp_server"
            ]
        }
    }
}

实现细节

该实现使用 PyGuitarPro 库来解析和操作 Guitar Pro 文件。MCP 服务提供了一个简单的 API 来访问 PyGuitarPro 库的功能。

许可证

本项目基于 MIT 许可证授权。