MCP Interface for Teenage Engineering EP-133 K.O. II

koii studio

使用 Claude 为 Teenage Engineering EP-133 K.O. II 制作节拍、歌曲和声音。

一个 MCP 服务，可让 Claude 通过 MIDI 与你一起在 EP-133 K.O. II 上制作节拍和歌曲。 你来描述音乐；Claude 会用一种简洁、严格的文本记谱法编写模式，在你的设备上播放， 在你调整时循环播放，并将它们编排成歌曲。

@bpm 92
@swing 58

kick:  x... ..x. x... ....
snare: .... x... .... x..o
hat:   x.x. x.x. x.x. x.xX

安装

需要 Python 3.9–3.12，以及一台通过 USB-C 连接的 EP-133。（Python 3.13 也能使用，但 负责与 MIDI 硬件通信的 python-rtmidi 目前没有适用于它的预编译 wheel，因此 会从源代码编译。）

git clone https://github.com/benjaminr/mcp-koii.git
cd mcp-koii
uv venv --python 3.12 .venv
uv pip install -r requirements.txt

# Add to Claude Desktop
mcp install koii_studio_server.py --name koii-studio -e .

# Or try it in the MCP inspector
mcp dev koii_studio_server.py -e .

对于 Claude Code：claude mcp add koii-studio -- /path/to/mcp-koii/.venv/bin/python /path/to/mcp-koii/koii_studio_server.py。

制作音乐

向 Claude 提出类似 “连接到我的 K.O. II，我们来做一段慢速 boom-bap 节拍” 的请求， 或者使用 make_a_beat 提示词。典型流程如下：

1. connect()：自动查找 EP-133。open_visualiser() 会实时显示所有内容。
2. Claude 编写一个模式，使用 check_pattern 检查，然后运行 play(..., loop=True)。
3. 你说出想要如何修改。每次新的 play 都会在当前循环结束时切换， 因此调整期间律动不会中断。
4. save_pattern("verse", ...) 会保存你喜欢的版本（保存在 ~/.koii-studio/library.json）。
5. save_song("track", "intro x2, verse x4, verse+bassline x4, chorus x8, outro")，然后 执行 play("track")。
6. export_midi("track") 会为你的 DAW 写入一个 .mid 文件。

可视化界面

该服务还会运行一个实时页面 **http://127.0.0.1:8133**（让 Claude 执行 open_visualiser）。 无论是谁触发操作，页面都会显示所有发生的事情：Claude 的工具调用、你的编辑，以及 你在设备上按下的打击垫。

它有四个视图，各司其职，可从顶部栏切换（并通过链接访问：#beat、#song、 #sounds、#device）。GUIDE.md 通过带注释的 屏幕截图逐一介绍各个视图。

视图	用途	内容
Beat	制作模式	设备模拟器和键盘、模式编辑器、模式列表
Song	编排	歌曲选择器和编排网格，以及可供拖入的模式列表
Sounds	制作声音	声音设计器、采样器和套件制作器
Device	查看 EP-133 上的内容	打开的项目及其全部 48 个打击垫（点击即可更改）、音色包、采样库和备份

在宽度至少为 1100 × 600 的窗口中，每个视图都能在一个屏幕内完整显示，无需滚动页面：各模块 共享窗口高度，较长的列表和设计器控件在模块内部滚动，设备 模拟器和打击垫映射会缩小以适应窗口。较小的窗口则会整页滚动。顶部栏 （传输控制、当前播放、连接状态）和实时信息条始终可见，日志 则以抽屉形式打开。按空格键可播放当前视图的内容：Beat 中播放模式，Song 中播放 歌曲，Sounds 中播放正在设计的声音。每个视图的布局都可单独调整并保存。

• **KO II 模拟器：**播放音符时，音垫会亮起（橙色）；在设备上按下音垫时也会亮起（蓝色）；显示屏会显示小节和拍。点击音垫即可试听。
• Pattern 编辑器，以三种视图呈现同一段 Pattern：
  • 网格：步进音序器。使用画笔绘制（击打、重音、装饰音、力度 1–9、延音、休止）；按住 Shift 拖动可添加延音，右键单击可擦除。可添加音轨和小节、输入贝斯线。? 键会说明每个符号和颜色。
  • **文本：**乐谱记法本身，输入时会检查，并可点击错误。
  • **记谱：**乐谱，包括鼓谱表，以及为有音高的音轨提供的低音谱表或高音谱表。
• 播放和停止：每个 ▶ 都可切换播放状态：再次按下（或按空格键）即可停止。顶部栏的 ▶、空格键和设备上的 PLAY 会播放你上次使用的模块，即 Pattern 编辑器或编曲器；顶部按钮会显示当前模块，该模块上会显示 ▶ 空格键徽标。编曲器的 ▶ 和每个库条目的 ▶ 会播放各自的内容，并在播放时显示 ■。按下播放会立即切换；一个循环设置适用于所有内容。开启实时编辑后，循环播放的 Pattern 每次更改都会在当前播放轮次结束时切换。撤销和重做（⌘Z / ⇧⌘Z）。
• **库和编曲器：**可保存的 Pattern，可打开、播放和删除；旁边是歌曲网格，带有自己的歌曲选择器（打开、命名、保存、删除、新建）。行是声部（每个 Pattern 占一行），列是乐段：点亮同一列中的多个单元格即可叠加播放 Pattern，添加列即可依次播放，并使用 − / + 设置每个乐段的重复次数。列的宽度会随播放时长变化，因此歌曲结构一目了然，正在播放的乐段也会亮起。从列表中拖入 Pattern：拖到最底部的空声部可新建声部，拖到单元格或乐段上可叠加到该处，拖到 + 上可新建乐段。拖动乐段标题可调整顺序，上下移动声部（最上方亮起的声部决定该乐段的速度）。网格和文本格式（intro x2, verse+bass x4）会保持同步，因此也可以直接输入。Pattern 可下载为 .mid 文件。
• 活动记录：Claude 发出的每次 MCP 调用；其中的 Pattern 可通过在编辑器中打开来查看。
• **实时电平条：**EP-133 也是一台 USB 音频设备，因此顶部栏会有一个电平条，显示它实际播放的内容：以 LED 列显示频谱，立体声电平表带有峰值保持和削波指示灯，并显示峰值电平。它只监听，不会播放音频。一旦浏览器获得使用 EP-133 音频输入的权限，每次插入 EP-133 后都会自动开始监听，且绝不会改用麦克风。点击电平条可停止或开始监听（停止后，之后访问时也会保持关闭），也可以切换为浏览器模拟器的声音。
• **采样：**EP-133 的采样库（全部 999 个槽位），提供搜索、波形、元数据、在设备上播放、WAV 下载和带进度显示的备份。此功能使用通过逆向工程得知的设备私有文件协议，参见 ep-series-sysex；使用时请关闭 TE 的 EP Sample Tool，因为设备一次只能处理一个文件会话。
• **声音设计：**分层合成器和采样器，以设备自身的 46,875 Hz 采样率渲染（与 Claude 使用的引擎相同）：
  • **设计：**最多六个层（模拟、FM、拨弦、模态、金属、加法、噪声和采样引擎），每层带有包络、音高下滑、扫频滤波器和 LFO，并可接入效果链（EQ、过载、低保真、压缩器、瞬态、合唱、延迟、混响、声场宽度）。
  • **分析与试听：**波形、频谱和频谱图，以及音高、响度、明亮度和设备上最接近的声音。可在此试听，也可通过 EP-133 的输出试听。
  • **探索：**带锁定参数的变体、向另一种声音渐变，以及已保存设计的库。
  • **采样：**录制 EP-133 的声音，将 Pattern 渲染为与速度同步的循环片段，加载文件、编辑（裁剪、淡入淡出、反转、移调、拉伸）并按击打点切片。
  • **音色组：**一组包含十二种声音的风格音色（808、909、低保真、原声、工业、故障）。
  • **上传：**自动检测根音和微调，查找无缝循环并设置播放模式，让音垫能准确演奏音高并保持延音。上传需要完整备份；不会触碰 koii studio 未上传的声音，并会根据设备自身的校验和进行检查。参见 SOUND_DESIGN.md。
• **自定义布局：**按 layout 可移动模块（拖动标题）、调整模块大小（拖动角落）并隐藏模块；还可重新排列或隐藏模块内部的部分内容，并拖动双栏区域之间的分隔线。随时点击 ▾ 可折叠模块。布局保存在此浏览器中；点击 reset 可恢复默认布局。
• 音色包：~/.koii-studio/packs 中的演示和音色组（koii studio 不附带任何音色包；可让 Claude 创建），每个音色包都包含采样、项目音垫布局、Pattern、歌曲和鸣谢信息。点击安装会将采样上传到空槽位（已存在的采样会重复使用）、打开项目并填充音垫，还会添加歌曲；点击移除采样会删除采样以释放空间并清空对应音垫，同时保留歌曲。
• **项目：**音垫设置面板会显示当前打开的项目，并可打开其他项目。
• **音垫设置：**点击模拟设备上的音垫，即可查看它在真实设备上播放的内容，并实时更改其声音槽位、MIDI 通道、播放模式或力度。这样就能将音垫变成旋律音色：为键盘音色指定通道 3，用 set_alias("chords", "ch3") 为该通道命名一次，Pattern 的 chords 音轨便会以准确音高播放。参见 DEVICE.md。
• **没有设备？**选择右上角的 Browser simulator，即可使用本页面合成并播放鼓和贝斯。 要在没有 Claude 的情况下运行：python -m koii_studio.visualiser（或 koii-studio）。启动时，如果 EP-133 已连接，就会连接到它（使用 --no-connect 可跳过）。设置： KOII_STUDIO_WEB_PORT（默认值为 8133；如果端口已被占用，则使用下一个空闲端口），以及 KOII_STUDIO_WEB=off 以禁用它。它只监听 localhost，并忽略来自其他网站的命令。

记谱法

完整规范：NOTATION.md。简要说明：

kick: x...x...	每种声音占一行；一个字符 = 一步（一个 16 分音符）
x X o 1–9	击打、重音、弱奏、力度等级 1–9
. -	休止、延续前一个音符
空格、|	忽略；可用于划分节拍
@bpm @swing @grid	速度、摇摆（50–75）、步长
@map bass = ch2 + bass notes: C1 Eb1 G0	使用 MIDI 通道的带音高声部
verse x4, chorus+bass x2	编排：使用 xN 重复，使用 + 叠加

声音可使用套件别名（kick、snare、hat、oh、clap……）、打击垫标签（A1、B.、CEnter）或 MIDI 音符命名。show_kit 可显示所有名称，set_alias 可添加自定义名称。错误会以带行号和列号的提示返回，例如： line 2: 'snare' has 15 steps, which doesn't divide the longest track 'kick' (16 steps)。

设备设置

鼓组无需设置。对于贝斯线和旋律，请为打击垫指定独立的 MIDI 通道：koii studio 可通过 USB 完成此操作（使用 set_pad，或在 Device 视图中点击打击垫），也可以在 Sound Edit 中手动设置（OS 2.0+）。力度变化（o、X、1–9）无需设置。详情、来源及硬件验证情况见 DEVICE.md。

工具

工具
list_midi_ports、connect、disconnect、status	连接
check_pattern	验证并显示节奏型，但不播放（无需设备）
play、stop	播放节奏型文本、已保存的名称、分层内容或编排；可循环播放并无缝切换
audition	试听一种声音或一个打击垫
save_pattern、save_song、show、list_library、delete	资源库
export_midi	写入 .mid 文件（无需设备）
export_musicxml	为节奏型生成乐谱（MuseScore、Dorico、Sibelius……）
list_device_sounds、play_sample	EP-133 上存储的采样
backup_device、cancel_backup	将所有采样（WAV）和项目复制到 ~/.koii-studio/backups
upload_sample、delete_upload	将 WAV 放入设备（转换为 46,875 Hz），或移除 koii studio 自行上传的内容
sound_presets、sound_design_schema	起始方案，以及所有引擎、效果和设置
design_sound、vary_sound、morph_sounds	渲染并描述一种设计（显示在可视化界面中）、生成变体、进行变形
save_design、list_designs	设计资源库，以及录制和加载的来源
upload_design、change_sound_settings	将设计作为乐器放入设备（根音、循环、播放模式）；直接更改已上传内容的设置
make_kit、kit_status、chop_source	创建包含十二种声音的风格套件；从录音切片；将内容上传到同一行的槽位
list_packs、install_pack、remove_pack、pack_status	采样包：一次性将示例或套件的采样、项目的打击垫、节奏型和歌曲放入 EP-133，或从中移除采样以释放空间
open_project	通过 USB 在 EP-133 上打开另一个项目（1–9）
get_pads、set_pad、undo_pad_change	通过 USB 读取或更改 EP-133 上的打击垫：声音槽位、MIDI 通道、播放模式、音量、包络、声像（实时生效、已验证、可撤销）
open_visualiser	打开实时浏览器视图
show_kit、set_alias、remove_alias、list_factory_sounds	套件

提示词：notation_guide、device_guide、sound_design_guide、make_a_beat、design_a_sound。

开发

uv pip install -r requirements-dev.txt
.venv/bin/python -m pytest

测试会从多个方面检查记谱法：解析器模糊测试、生成的乐谱必须与实际播放内容一致的模式、由 music21 重新读取的 MusicXML，以及通过浏览器编辑器自身 JavaScript 进行的往返测试（需要 Node）。

代码位于 koii_studio/：notation（解析器）、sequence（时序、摇摆节奏、编排、MIDI 文件）、player（后台播放）、library（持久化）、studio（将各部分整合起来）、events（实时更新）、visualiser（网页服务器，页面位于 koii_studio/static/）和 server（MCP 工具）。设备文件：files（SysEx 文件协议）、backup 和 samples。声音设计：koii_studio/synth/（schema 是设计格式，engine 和 dsp 负责渲染，analysis、用于设备设置的 instrument、variation、edit、presets，以及 designs、sources 和 factory 存储库），并由 sound_design 整合。设置 KOII_STUDIO_HOME，可将库、设计和来源存放到其他位置。

致谢

• 感谢 Teenage Engineering 推出 EP-133 K.O. II。
• 感谢 Anthropic 提供 Claude 和 Model Context Protocol。
• 感谢 MIDO 提供 MIDI 处理功能。
• 感谢 Kevin Morrill 开发的 ep-series-sysex，它为样本、备份、音色包和打击垫设置提供了逆向工程得到的文件协议（MIT；参见 THIRD_PARTY_NOTICES.md）。

风险自负

koii studio 是一个业余项目，按现状提供，不附带任何保证（参见 LICENSE）。除了通过 MIDI 播放音符，它还会通过一种 teenage engineering 未记录或支持的专有协议写入 EP-133 自身存储：上传和删除样本，以及更改打击垫和当前打开的项目。它会谨慎确保操作安全（上传前进行完整备份，只修改或删除它自己上传的内容，并读取和检查每次写入的数据），但固件更新或意外响应仍可能导致声音、项目或设置丢失，或者需要重启设备。请自行保留备份，在 koii studio 运行时关闭 TE 的 EP Sample Tool，并自行承担使用风险。

许可

koii studio 是基于 MIT 许可证发布的自由软件：你可以使用、修改和分享它，包括用于商业用途，前提是保留版权声明。

音频不属于 koii studio 的一部分：音色包自带音频，并在各自的 pack.json 中注明来源。构建过程中制作的演示音色包仅使用公有领域录音。截图：koii studio 自带页面。koii studio 与 teenage engineering 无关联，也未获其认可；EP-133 和 K.O. II 是其商标。