{"id":"ba1460b1-52ed-43fe-887c-6a13754e6cd4","slug":"mcp-koii","kind":"mcp","name":"mcp-koii","summary":"MCP Server for Teenage Engineering EP-133 KO-II","owner":"benjaminr","repoUrl":"https://github.com/benjaminr/mcp-koii","license":"MIT","licenseTier":"permissive","trust":"community","stars":32,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-04-14T07:15:27.000Z","addedAt":"2026-10-14T03:48:01.751Z","logoUrl":"https://avatars.githubusercontent.com/u/1671906?u=a39508367a636bba948ba4292ce2ad5d3e936f94&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge","design-media"],"tags":["midi","midi-controller","music","teenage-engineering","ep-133","ko-ii","model-context-protocol-servers"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T05:34:07.489Z","sample":false,"url":"https://conduits.dev/tools/mcp-koii","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# koii studio\n\nMake beats, songs and sounds for the Teenage Engineering EP-133 K.O. II, with Claude.\n\n<img src=\"./screenshots/overview.jpg\" alt=\"koii studio: the simulated EP-133, a boom-bap pattern with a bassline in the grid editor, and the pattern list\" width=\"900\">\n\nAn MCP server that lets Claude make beats and songs with you on an EP-133 K.O. II over MIDI.\nYou talk about the music; Claude writes patterns in a small, strict text notation, plays\nthem on your device, loops them while you iterate, and arranges them into songs.\n\n```\n@bpm 92\n@swing 58\n\nkick:  x... ..x. x... ....\nsnare: .... x... .... x..o\nhat:   x.x. x.x. x.x. x.xX\n```\n\n## Install\n\nRequires Python 3.9–3.12 and an EP-133 connected over USB-C. (Python 3.13 works too, but\n`python-rtmidi`, which talks to the MIDI hardware, has no prebuilt wheels for it yet and\nwill compile from source.)\n\n```bash\ngit clone https://github.com/benjaminr/mcp-koii.git\ncd mcp-koii\nuv venv --python 3.12 .venv\nuv pip install -r requirements.txt\n\n# Add to Claude Desktop\nmcp install koii_studio_server.py --name koii-studio -e .\n\n# Or try it in the MCP inspector\nmcp dev koii_studio_server.py -e .\n```\n\nFor Claude Code: `claude mcp add koii-studio -- /path/to/mcp-koii/.venv/bin/python /path/to/mcp-koii/koii_studio_server.py`.\n\n## Making music\n\nAsk Claude something like *\"connect to my K.O. II and let's make a slow boom-bap beat\"*,\nor use the `make_a_beat` prompt. A typical session:\n\n1. `connect()`: finds the EP-133 automatically. `open_visualiser()` shows it all live.\n2. Claude writes a pattern, checks it with `check_pattern`, and runs `play(..., loop=True)`.\n3. You say what to change. Each new `play` switches **at the end of the current loop**,\n   so the groove never stops while you iterate.\n4. `save_pattern(\"verse\", ...)` keeps versions you like (saved to `~/.koii-studio/library.json`).\n5. `save_song(\"track\", \"intro x2, verse x4, verse+bassline x4, chorus x8, outro\")` and\n   `play(\"track\")`.\n6. `export_midi(\"track\")` writes a `.mid` file for your DAW.\n\n## The visualiser\n\nThe server also runs a live page at **http://127.0.0.1:8133** (ask Claude to `open_visualiser`).\nIt shows everything that happens, whoever does it: Claude's tool calls, your edits, and\npads you press on the device.\n\nIt has four views, one per job, switched from the top bar (and linked: `#beat`, `#song`,\n`#sounds`, `#device`). **[GUIDE.md](GUIDE.md)** walks through each one with annotated\nscreenshots.\n\n| View | For | What's in it |\n|------|-----|--------------|\n| **Beat** | making a pattern | the device simulator and keyboard, the pattern editor, the pattern list |\n| **Song** | arranging | the song picker and arranger grid, the pattern list to drag from |\n| **Sounds** | making sounds | the sound designer, sampler and kit maker |\n| **Device** | what's on the EP-133 | the open project and all 48 of its pads (click one to change it), packs, the sample library and backups |\n\nOn a window at least 1100 × 600, each view is one screen with no page scrolling: modules\nshare the height, long lists and the designer's controls scroll inside them, and the device\nsimulator and the pad map scale down to fit. Smaller windows scroll as a page. The top bar\n(transport, now playing, connection) and the live strip are always there, and the log\nopens as a drawer. Space plays what the view is about: the pattern in Beat, the\nsong in Song, the sound being designed in Sounds. Each view's layout is arranged and kept\nseparately.\n\n- **KO II simulator:** pads light as notes play (orange) and when you press them on the\n  device (blue); the display shows bar and beat. Click a pad to hear it.\n- **Pattern editor** with three views of the same pattern:\n  - **Grid:** a step sequencer. Paint with brushes (hit, accent, ghost, levels 1–9, hold,\n    rest); shift-drag holds, right-click erases. Add tracks and bars, type basslines. **? key**\n    explains every symbol and colour.\n  - **Text:** the notation itself, checked as you type, with clickable errors.\n  - **Notation:** sheet music, with a drum staff and a bass or treble staff for pitched tracks.\n- **Play and stop:** every ▶ toggles: press it again (or Space) to stop. The top bar's ▶,\n  Space and the device's PLAY play whichever you used last, the pattern editor or the\n  arranger; the top button says which, and that module wears a **▶ space** badge. The\n  arranger's ▶ and each library row's ▶ play their own thing and show ■ while it plays.\n  Pressing play switches at once; one **loop** setting covers everything. Turn on **Live\n  edit** and every change to a looping pattern switches in at the end of the current pass.\n  Undo and redo (⌘Z / ⇧⌘Z).\n- **Library and arranger:** saved patterns, to open, play and delete, beside a song grid\n  with its own song picker (open, name, save, delete, new). Rows are lanes (one per pattern) and columns are sections: light\n  several cells in a column to layer patterns, add columns to play them in turn, and set\n  each section's repeats with − / +. Columns are as wide as they play, so the song's\n  shape shows at a glance, and the playing section lights up. Drag patterns in from the\n  list: onto the empty lane at the bottom for a new lane, onto a cell or a section to\n  layer it there, or onto **+** for a new section. Drag section headers to\n  reorder them, and move lanes up or down (the top lit lane sets a section's tempo). The\n  grid and the text form (`intro x2, verse+bass x4`) stay in step, so you can type too.\n  Patterns download as `.mid` files.\n- **Activity:** each MCP call Claude makes, with **Open in editor** for its patterns.\n- **Live strip:** the EP-133 is also a USB audio device, so a strip across the top bar\n  shows what it actually plays: spectrum as LED columns, stereo meters with peak hold and\n  clip lights, and the peak level. It only listens. Once the browser may use the EP-133's\n  audio input, listening starts by itself whenever the EP-133 is plugged in, and it never\n  falls back to your microphone. Click the strip to stop or start it (stopping keeps it\n  off on later visits), or switch it to the browser simulator's voices.\n- **Samples:** the EP-133's sample library (all 999 slots), with search, waveforms,\n  metadata, play-on-device, WAV download and backups with progress. This uses the device's\n  private file protocol as reverse-engineered by\n  [ep-series-sysex](https://github.com/kmorrill/ep-series-sysex); close TE's EP Sample Tool\n  while using it, since the device handles one file session at a time.\n- **Sound design:** a layered synthesiser and sampler that renders at the device's own\n  46,875 Hz (the same engine Claude uses):\n  - **Design:** up to six layers (analog, FM, pluck, modal, metal, additive, noise and\n    sample engines), each with envelopes, a pitch drop, a sweeping filter and LFOs, into\n    an effects chain (EQ, drive, lofi, compressor, transient, chorus, delay, reverb,\n    width).\n  - **Analysis and preview:** waveform, spectrum and spectrogram, pitch, loudness and\n    brightness, and the closest sounds already on the device. Play it here or through the\n    EP-133's own output.\n  - **Exploring:** variations with locks, morphing towards another sound, and a library\n    of saved designs.\n  - **Sample:** record the EP-133, bounce a pattern to a tempo-synced loop, load files,\n    edit (trim, fades, reverse, pitch, stretch) and chop at the hits.\n  - **Kit:** twelve sounds in a style (808, 909, lofi, acoustic, industrial, glitch).\n  - **Upload:** detects the root note and fine tune, finds a seamless loop and sets the\n    play mode, so pads play in tune and sustain. Uploads need a complete backup, never\n    touch sounds koii studio didn't upload, and are checked against the device's own checksum.\n    See **[SOUND_DESIGN.md](SOUND_DESIGN.md)**.\n- **Your own layout:** press **layout** to move modules (drag a header), resize them (drag\n  the corner) and hide them; reorder or hide the parts inside them; and drag the line\n  between two-column areas. **▾** collapses a module at any time. The layout is kept in\n  this browser; **reset** goes back to the default.\n- **Packs:** demos and kits in `~/.koii-studio/packs` (none come with koii studio; ask Claude\n  to build one), each with its samples, a project's pad\n  layout, patterns, songs and credits. **Install** uploads the samples to empty slots\n  (reusing any already there), opens the project and fills its pads, and adds the songs;\n  **remove samples** deletes them to free space and empties their pads, keeping the songs.\n- **Projects:** the pad settings panel shows which project is open and opens another.\n- **Pad settings:** click a pad on the simulated device to see what it plays on the real one,\n  and change its sound slot, MIDI channel, play mode or level there, live. This is how a\n  pad becomes a melodic voice: give a keys sound channel 3, name the channel once with\n  `set_alias(\"chords\", \"ch3\")`, and a pattern's `chords` track plays it in tune. See [DEVICE.md](DEVICE.md#playing-pitches-basslines-chords-melodies).\n- **No device?** Choose *Browser simulator* (top right) and the page plays synthesised\n  drums and bass itself.\n\nTo run it without Claude: `python -m koii_studio.visualiser` (or `koii-studio`). It connects to\nthe EP-133 on start if it's plugged in (`--no-connect` to skip that). Settings:\n`KOII_STUDIO_WEB_PORT` (default 8133; the next free port is used if it's taken) and `KOII_STUDIO_WEB=off`\nto disable it. It only listens on localhost and ignores commands from other websites.\n\n## The notation\n\nFull spec: **[NOTATION.md](NOTATION.md)**. The short version:\n\n| | |\n|-|-|\n| `kick: x...x...` | one line per sound; **one character = one step** (a 16th note) |\n| `x` `X` `o` `1`–`9` | hit, accent, ghost, level 1–9 |\n| `.` `-` | rest, hold the previous note |\n| spaces, `\\|` | ignored; use them to group beats |\n| `@bpm` `@swing` `@grid` | tempo, swing (50–75), step length |\n| `@map bass = ch2` + `bass notes: C1 Eb1 G0` | pitched lines on a MIDI channel |\n| `verse x4, chorus+bass x2` | arrangements: repeat with `xN`, layer with `+` |\n\nSounds are named with kit aliases (`kick`, `snare`, `hat`, `oh`, `clap`, …), pad labels\n(`A1`, `B.`, `CEnter`) or MIDI notes. `show_kit` shows them all and `set_alias` adds your\nown. Mistakes come back as errors with line and column, e.g.\n`line 2: 'snare' has 15 steps, which doesn't divide the longest track 'kick' (16 steps)`.\n\n## Device setup\n\nDrums need no setup. For basslines and melodies, give the pad its own MIDI channel: koii studio\ndoes it over USB (`set_pad`, or click the pad in the Device view), or set it by hand in Sound\nEdit (OS 2.0+). Dynamics (`o`, `X`, `1`–`9`) work with no setup. Details, with\nsources and what has been checked on hardware, are in **[DEVICE.md](DEVICE.md)**.\n\n## Tools\n\n| Tool | |\n|------|-|\n| `list_midi_ports`, `connect`, `disconnect`, `status` | connection |\n| `check_pattern` | validate and show a pattern without playing (no device needed) |\n| `play`, `stop` | play pattern text, saved names, layers or arrangements; loop and switch seamlessly |\n| `audition` | hear one sound or pad |\n| `save_pattern`, `save_song`, `show`, `list_library`, `delete` | the library |\n| `export_midi` | write a `.mid` file (no device needed) |\n| `export_musicxml` | write sheet music for a pattern (MuseScore, Dorico, Sibelius…) |\n| `list_device_sounds`, `play_sample` | the samples stored on the EP-133 |\n| `backup_device`, `cancel_backup` | copy every sample (WAV) and project to `~/.koii-studio/backups` |\n| `upload_sample`, `delete_upload` | put a WAV on the device (converted to 46,875 Hz), or remove koii studio's own uploads |\n| `sound_presets`, `sound_design_schema` | starting points, and every engine, effect and setting |\n| `design_sound`, `vary_sound`, `morph_sounds` | render and describe a design (shown in the visualiser), make variations, morph |\n| `save_design`, `list_designs` | the design library, plus recorded and loaded sources |\n| `upload_design`, `change_sound_settings` | put a design on the device as an instrument (root, loop, play mode); change an upload's settings in place |\n| `make_kit`, `kit_status`, `chop_source` | twelve-sound kits in a style; slices from a recording; uploads to slots in a row |\n| `list_packs`, `install_pack`, `remove_pack`, `pack_status` | sample packs: put a demo or kit's samples, a project's pads, patterns and songs on the EP-133 in one go, or take its samples off to free space |\n| `open_project` | open another project (1–9) on the EP-133 over USB |\n| `get_pads`, `set_pad`, `undo_pad_change` | read or change pads on the EP-133 over USB: sound slot, MIDI channel, play mode, level, envelope, pan (live, checked, undoable) |\n| `open_visualiser` | open the live browser view |\n| `show_kit`, `set_alias`, `remove_alias`, `list_factory_sounds` | the kit |\n\nPrompts: `notation_guide`, `device_guide`, `sound_design_guide`, `make_a_beat`, `design_a_sound`.\n\n## Development\n\n```bash\nuv pip install -r requirements-dev.txt\n.venv/bin/python -m pytest\n```\n\nThe tests check the notation from several sides: parser fuzzing, generated patterns whose\nsheet music must match what plays, MusicXML re-read by [music21](https://www.music21.org/),\nand a round trip through the browser editor's own JavaScript (needs Node).\n\nThe code is in `koii_studio/`: `notation` (parser), `sequence` (timing, swing, arrangements,\nMIDI files), `player` (background playback), `library` (persistence), `studio` (ties it\ntogether), `events` (live updates), `visualiser` (the web server, with the page in\n`koii_studio/static/`) and `server` (MCP tools). Device files: `files` (the SysEx file protocol),\n`backup` and `samples`. Sound design: `koii_studio/synth/` (`schema` is the design format,\n`engine` and `dsp` render it, `analysis`, `instrument` for device settings, `variation`,\n`edit`, `presets`, and the `designs`, `sources` and `factory` stores), joined up by\n`sound_design`. Set `KOII_STUDIO_HOME` to keep the library, designs and sources somewhere else.\n\n## Acknowledgements\n\n- [Teenage Engineering](https://teenage.engineering/) for the EP-133 K.O. II.\n- [Anthropic](https://www.anthropic.com/) for Claude and the Model Context Protocol.\n- [MIDO](https://mido.readthedocs.io/) for MIDI handling.\n- [ep-series-sysex](https://github.com/kmorrill/ep-series-sysex) by Kevin Morrill, for the\n  reverse-engineered file protocol behind samples, backups, packs and pad settings (MIT; see\n  [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)).\n\n## Use at your own risk\n\nkoii studio is a hobby project, provided as is, with no warranty (see [LICENSE](LICENSE)).\nBesides playing notes over MIDI, it writes to the EP-133's own storage through a private\nprotocol that teenage engineering doesn't document or support: uploading and deleting\nsamples, and changing pads and the open project. It takes care to do that safely (a\ncomplete backup before any upload, only its own uploads changed or deleted, every write read\nback and checked), but a firmware update or an unexpected reply could still lose sounds,\nprojects or settings, or leave the device needing a restart. Keep your own backups, close\nTE's EP Sample Tool while koii studio is running, and use it at your own risk.\n\n## Licence\n\nkoii studio is free software under the [MIT licence](LICENSE): use it, change it and share it,\nincluding commercially, as long as the copyright notice stays with it.\n\nAudio isn't part of koii studio: packs bring their own, with their sources credited in each\n`pack.json`. The demo packs made while building it use only public-domain recordings.\nScreenshots: koii studio's own page. koii studio isn't affiliated with or endorsed by teenage engineering; EP-133 and\nK.O. II are their trademarks.\n"}