面向 Teenage Engineering EP-133 K.O. II 的 MCP 接口

<img src="./mcp.jpg" width="318"><img src="./koii.jpg" width="200">

本项目是一个模型上下文协议 (MCP) 服务器，通过 MIDI 充当 Teenage Engineering EP-133 K.O. II 采样器的控制器。

功能特性

• 通过 MIDI 连接到您的 EP-133 K.O. II 设备
• 通过文本命令播放音符和乐段
• 查看默认的打击垫配置以了解声音映射
• 使用简单的基于文本的语法创建和播放鼓点乐段
• 支持多种乐器参考方法（打击垫标签、MIDI 音符、乐器名称、声音名称）
• 同时播放鼓点乐段中的多个乐器
• 通过 MCP 与 Claude 集成

安装

前提条件

• Python 3.8 或更高版本
• mido (MIDI 处理)
• mcp (模型上下文协议 SDK)

快速安装

# 安装所需的软件包
pip install mido "mcp[cli]"

# 克隆存储库
git clone https://github.com/benjaminr/mcp-koii.git
cd mcp-koii

# 安装 MCP 服务器
mcp install koii_server.py:server -e .

与 Claude Desktop 一起使用

1. 确保您的 EP-133 K.O. II 通过 USB 连接到您的计算机。

2. 启动启用 MCP 的 Claude Desktop。

3. 通过向 Claude 提出自然语言问题来开始控制您的 EP-133 K.O. II，例如：

   • "列出可用的 MIDI 端口"
   • "连接到 EP-133 设备"
   • "播放 C 大调音阶"
   • "播放一个鼓点乐段，在第 1 拍和第 3 拍上是底鼓，在第 2 拍和第 4 拍上是军鼓，在每 8 分音符上是踩镲"

在开发模式下运行

您可以在开发模式下运行 MCP 服务器，以便在没有 Claude Desktop 的情况下对其进行测试：

# 使用检查器 UI 运行
mcp dev koii_server.py:server -e .

功能和命令

基本命令

• 列出可用的 MIDI 端口: 显示系统上所有可用的 MIDI 输出端口。
• 连接到 MIDI 设备: 通过名称或端口号连接到 EP-133 K.O. II。
• 断开连接: 关闭与当前 MIDI 设备的连接。

播放音符和乐段

• 播放音符: 播放具有指定力度和持续时间的单个音符。
• 播放乐段: 播放具有时序信息的音符序列。
• 播放鼓点乐段: 播放基于文本的鼓点乐段。

声音浏览器

• 列出声音类别: 查看可用的声音类别（底鼓、军鼓等）。
• 列出类别中的声音: 浏览特定类别中的声音。
• 获取默认打击垫配置: 查看默认情况下哪些声音映射到每个打击垫。

MIDI 实现

EP-133 K.O. II 响应以下 MIDI 消息：

• 音符开/关: 触发打击垫上的声音 (C2-B5, 音符 36-83)

鼓点乐段语法

鼓点乐段系统支持四种不同的方式来引用声音：

1. 使用打击垫引用：

x...x...x...x...  # A.
....x.......x...  # A2
x.x.x.x.x.x.x.x.  # A5

2. 使用 MIDI 音符编号：

x...x...x...x...  # 36
....x.......x...  # 40
x.x.x.x.x.x.x.x.  # 43

3. 使用声音名称：

x...x...x...x...  # "MICRO KICK"
....x.......x...  # "NT SNARE"
x.x.x.x.x.x.x.x.  # "NT HH CLOSED"

4. 混合引用：

x...x...x...x...  # A.       (打击垫引用)
....x.......x...  # 40       (MIDI 音符)
......x.........  # "NT RIDE" (声音名称)

乐段格式

• 每行代表不同的乐器/声音
• 'x' 或 'X' 表示击打（高力度）
• 'o' 或 'O' 表示较轻的击打（较低力度）
• '.' 表示没有击打
• 每个位置代表一个 16 分音符
• '#' 之后的注释指定要使用任何引用方法触发的声音
• 可以同时触发多个乐器，它们的击打重叠

故障排除

• 未找到 MIDI 端口: 确保您的 EP-133 K.O. II 已连接并已开启电源。
• 连接问题: 尝试重新连接 USB 电缆或重新启动您的 EP-133。
• 音符不播放: 验证设备是否处于正确的 MIDI 模式。
• 多个乐器无法同时播放: 使用更高的 BPM 值，以确保 EP-133 K.O. II 可以在播放期间处理所有音符。
• 未知乐器: 使用引号引起来的精确乐器名称、打击垫标签、MIDI 音符或声音名称。

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• Teenage Engineering 感谢他们提供的 EP-133 K.O. II。
• Anthropic 感谢他们提供的 Claude 和模型上下文协议。
• MIDO 感谢他们提供的 MIDI 处理库。