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

koii studio

Claude と一緒に、Teenage Engineering EP-133 K.O. II 用のビート、曲、サウンドを作りましょう。

Claude と一緒に、MIDI 経由で EP-133 K.O. II のビートや曲を作れる MCP サーバーです。 音楽について話すと、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 はまだビルド済みホイールが用意されていないため、 ソースからコンパイルされます。）

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 に接続して、ゆっくりしたブーンバップのビートを作ろう」 のように頼むか、 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 のツール呼び出し、編集内容、デバイスで押したパッドなど、あらゆる動作が表示されます。

用途ごとに 1 つずつ、上部バーから切り替えられる 4 つのビューがあります（リンク先：#beat、 #song、#sounds、#device）。各ビューの詳しい説明と注釈付きスクリーンショットは、 GUIDE.md をご覧ください。

ビュー	用途	内容
Beat	パターンの作成	デバイスシミュレーターとキーボード、パターンエディター、パターンリスト
Song	アレンジ	曲の選択とアレンジ用グリッド、ドラッグ元となるパターンリスト
Sounds	サウンドの作成	サウンドデザイナー、サンプラー、キットメーカー
Device	EP-133 の内容確認	開いているプロジェクトと 48 個すべてのパッド（クリックして変更できます）、パック、サンプルライブラリ、バックアップ

幅 1100 × 600 以上のウィンドウでは、各ビューがページスクロールなしの 1 画面に収まります。モジュールは高さを共有し、 長いリストやデザイナーのコントロールは各モジュール内でスクロールし、デバイスシミュレーターとパッドマップは画面に収まるよう縮小されます。 小さなウィンドウではページ全体がスクロールします。上部バー （トランスポート、再生中の内容、接続状態）とライブストリップは常に表示され、ログはドロワーとして開きます。 スペースキーを押すと、そのビューで扱っている内容が再生されます。Beat ではパターン、Song では曲、 Sounds ではデザイン中のサウンドが再生されます。各ビューのレイアウトは個別に配置され、保持されます。

• KO II シミュレーター： ノートの再生中はパッドがオレンジ色に光り、デバイス上で押すと青色に光ります。ディスプレイには小節と拍が表示されます。パッドをクリックすると音を聴けます。
• パターンエディター：同じパターンを3つの表示方法で編集できます。
  • グリッド： ステップシーケンサーです。ブラシ（ヒット、アクセント、ゴースト、レベル1〜9、ホールド、休符）で描き込みます。Shiftを押しながらドラッグするとホールドになり、右クリックすると消去できます。トラックや小節を追加したり、ベースラインを入力したりできます。?キーを押すと、すべての記号と色の説明が表示されます。
  • テキスト： 記譜を入力する表示です。入力中にチェックされ、エラーはクリックできます。
  • 譜面： ドラム譜と、音程のあるトラック用のベース譜またはト音譜を表示します。
• 再生と停止： ▶はすべてトグル式です。もう一度押すか、Spaceを押すと停止します。上部バーの▶、Space、デバイスのPLAYでは、最後に使用したパターンエディターかアレンジャーが再生されます。上部のボタンにどちらが選ばれているかが表示され、そのモジュールには**▶ spaceバッジが付きます。アレンジャーの▶と各ライブラリ行の▶はそれぞれ独自の内容を再生し、再生中は■が表示されます。再生を押すと、すぐに切り替わります。すべての再生に共通のループ**設定が適用されます。ライブ編集を有効にすると、ループ再生中のパターンを変更した際、現在の再生が終わった時点で切り替わります。元に戻す、やり直す（⌘Z / ⇧⌘Z）。
• ライブラリとアレンジャー： 保存したパターンを開いたり、再生したり、削除したりできるライブラリと、独自の曲選択メニュー（開く、名前を付ける、保存、削除、新規作成）を備えたソンググリッドが並んでいます。行はレーン（パターンごとに1つ）、列はセクションです。列内の複数のセルを点灯させてパターンを重ねたり、列を追加して順番に再生したり、− / +で各セクションのリピート回数を設定したりできます。列の幅は再生時間に合わせて変わるため、曲の構成がひと目で分かり、再生中のセクションが点灯します。リストからパターンをドラッグして、下部の空のレーンにドロップすると新しいレーンに、セルまたはセクションにドロップするとそこに重ねられます。**+**にドロップすると新しいセクションが作成されます。セクションのヘッダーをドラッグして順番を変え、レーンを上下に移動できます（最上段の点灯中のレーンがセクションのテンポを決めます）。グリッドとテキスト形式（intro x2, verse+bass x4）は連動するため、テキストで入力することもできます。パターンは.midファイルとしてダウンロードされます。
• アクティビティ： Claudeが行った各MCP呼び出しを表示します。パターンにはエディターで開くボタンが付いています。
• ライブストリップ： EP-133はUSBオーディオデバイスとしても機能します。そのため、実際に再生されている音を示すストリップが上部バーに表示されます。LED列のスペクトラム、ピークホールドとクリップ表示付きのステレオメーター、ピークレベルが確認できます。入力を聴くだけで、音声には手を加えません。ブラウザーでEP-133の音声入力が一度許可されると、EP-133を接続するたびに自動で再生音の取り込みが始まり、マイクに切り替わることはありません。ストリップをクリックすると停止または開始できます（停止すると、次回以降もオフのままです）。または、ブラウザーシミュレーターの音声に切り替えられます。
• サンプル： EP-133のサンプルライブラリ（全999スロット）を検索できます。波形、メタデータ、デバイス上での再生、WAVダウンロード、進行状況表示付きのバックアップにも対応しています。これは、リバースエンジニアリングされたデバイスの独自ファイルプロトコルをep-series-sysex経由で使用します。デバイスは一度に1つのファイルセッションしか処理できないため、使用中はTEのEP Sample Toolを閉じてください。
• サウンドデザイン： デバイスと同じ46,875 Hzでレンダリングするレイヤー型シンセサイザーとサンプラーです（Claudeが使うエンジンと同じです）。
  • デザイン： 最大6つのレイヤー（アナログ、FM、プラック、モーダル、メタル、加算合成、ノイズ、サンプルの各エンジン）を使えます。各レイヤーにはエンベロープ、ピッチドロップ、スイープフィルター、LFOを設定でき、さらにエフェクトチェーン（EQ、ドライブ、ローファイ、コンプレッサー、トランジェント、コーラス、ディレイ、リバーブ、幅）に送れます。
  • 分析とプレビュー： 波形、スペクトラム、スペクトログラム、ピッチ、音量、明るさ、デバイスにすでにある最も近いサウンドを表示します。ここで再生することも、EP-133本体の出力から再生することもできます。
  • 探索： ロック付きのバリエーション、別のサウンドへのモーフィング、保存済みデザインのライブラリを利用できます。
  • サンプル： EP-133を録音したり、パターンをテンポ同期ループにバウンスしたり、ファイルを読み込んだりできます。編集（トリミング、フェード、逆再生、ピッチ、ストレッチ）や、ヒット位置でのチョップにも対応しています。
  • キット： スタイル（808、909、ローファイ、アコースティック、インダストリアル、グリッチ）に合わせた12種類のサウンドです。
  • アップロード： ルート音と微調整値を検出し、シームレスなループを見つけて再生モードを設定するため、パッドを正しい音程で鳴らし、音を持続させられます。アップロードには完全なバックアップが必要です。また、koii studioがアップロードしていないサウンドには決して触れず、デバイス独自のチェックサムと照合します。詳しくは**SOUND_DESIGN.md**を参照してください。
• レイアウトのカスタマイズ： layoutを押すと、モジュールを移動（ヘッダーをドラッグ）、サイズ変更（角をドラッグ）、非表示にできます。モジュール内のパーツの順番を変えたり、非表示にしたり、2列の領域の間にある境界線をドラッグしたりすることもできます。**▾**を押すと、いつでもモジュールを折りたためます。レイアウトはこのブラウザーに保存され、resetでデフォルトに戻せます。
• パック： ~/.koii-studio/packsにあるデモとキットです（koii studioには付属していません。Claudeに作成を依頼してください）。それぞれにサンプル、プロジェクトのパッドレイアウト、パターン、曲、クレジットが含まれています。インストールすると、サンプルを空きスロットにアップロードし（すでにあるものは再利用します）、プロジェクトを開いてパッドに割り当て、曲を追加します。サンプルを削除すると、サンプルを削除して空き容量を確保し、対応するパッドを空にします。曲は残ります。
• プロジェクト： パッド設定パネルには現在開いているプロジェクトが表示され、別のプロジェクトを開くこともできます。
• パッド設定： シミュレートされたデバイス上のパッドをクリックすると、実機で再生される音を確認できます。そこでサウンドスロット、MIDIチャンネル、再生モード、レベルをリアルタイムで変更できます。これでパッドをメロディー音源として使えます。キーサウンドにチャンネル3を割り当て、set_alias("chords", "ch3")でチャンネルに一度だけ名前を付けると、パターンのchordsトラックで正しい音程を再生できます。詳しくはDEVICE.mdを参照してください。
• デバイスがない場合： 右上でブラウザーシミュレーターを選ぶと、ページ上でドラムとベースが合成されて再生されます。 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...	サウンドごとに 1 行を使用します。1 文字 = 1 ステップ（16 分音符）です
x X o 1–9	ヒット、アクセント、ゴーストノート、レベル 1～9
. -	休符、直前の音を保持
spaces, |	無視されます。拍をグループ化するのに使います
@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	スタイルに合わせた 12 サウンドのキット、録音からのスライス、スロットへの連続転送
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（Webサーバー。ページは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を設定してください。

謝辞

• EP-133 K.O. IIを提供したTeenage Engineering。
• ClaudeとModel Context Protocolを提供したAnthropic。
• MIDIの処理に使用したMIDO。
• サンプル、バックアップ、パック、パッド設定を扱うリバースエンジニアリングされたファイルプロトコルを提供した、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は同社の商標です。