# kobox

<p align="center">
  <img src="assets/kobox-poster.png" alt="Kobox — talk to Claude, play K.O. II" width="100%">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.9%2B-3776AB" alt="python 3.9+">
  <img src="https://img.shields.io/badge/MCP-stdio_server-111" alt="MCP stdio server">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license">
</p>

Play your **Teenage Engineering EP-133 K.O. II** by talking to Claude. kobox is a
small [MCP](https://modelcontextprotocol.io) server that turns plain language into
MIDI — trigger pads, lay down grooves, run scales — straight to the hardware.

> "Connect to my K.O. II, then play an ascending C minor pentatonic on group A."

That works. So does asking for a 16-step beat, a single note, or a melody in any of
eleven scales.

---

## Install — the easy way (Claude Code)

You don't need to know any Python. Claude does the setup.

1. Plug the K.O. II into your computer over USB and turn it on.
2. Paste this repo's URL into **Claude Code** and say: **"Install this MCP for me."**
   It reads [`CLAUDE.md`](CLAUDE.md) and handles the environment, dependencies,
   registration, and a connection check on its own.
3. Restart Claude Code, then say **"connect to my K.O. II"** and start playing.

## Install — one line (if you already use `uv`)

```bash
uvx --from git+https://github.com/yangyue1974/kobox kobox
```

Then point your MCP client at the command
`uvx --from git+https://github.com/yangyue1974/kobox kobox`.

## Claude Desktop

Desktop can't run setup commands. Install once on a machine that has Claude Code
(above), then copy the command + absolute path shown by `claude mcp get kobox`
into Desktop's MCP server config.

---

## Things to say

| You say | kobox does |
| --- | --- |
| "Connect to my K.O. II" | Auto-detects and opens the EP-133 MIDI port |
| "Trigger the pad printed 5 on group B" | Fires `B5` |
| "Play a 16-step groove with pads A., A0 and A1" | Sequences a beat with timing |
| "Run an ascending C major scale on group A" | Plays the scale by degrees |
| "Play C3, then F#4" | Sends raw notes |
| "What scales can you do?" | Lists all eleven |

## Tools

| Tool | Purpose |
| --- | --- |
| `connect` · `disconnect` | Open / close the device (auto-detects the EP-133) |
| `list_ports` | List available MIDI output ports |
| `trigger_pad` | Fire a pad by its printed label (`A.`, `A1`, `D9` …) |
| `play_note` | Play a MIDI note number or name (`C3`, `F#4`) |
| `play_pattern` | Sequence a series of hits with per-hit timing |
| `play_scale` | Play a melody as scale degrees — 11 scales, any root |
| `list_scales` | List the supported scales and their intervals |
| `device_info` | Report the device's note map and pad layout |

## How pads are named

A pad reference is the **group letter** (A–D) plus the **symbol printed on the
keypad** — not a 1-to-12 index. Within a group the labels run from the lowest note
upward:

```
.   0   enter   1   2   3   4   5   6   7   8   9
```

So `A.` is the lowest pad in group A and `A1` is the pad printed "1" (the fourth
one). The four groups sit in their own octave bands: A = MIDI 36–47, B = 48–59,
C = 60–71, D = 72–83. This was measured on real hardware, not guessed.

## What kobox deliberately doesn't do

- **It doesn't claim to know your sounds.** Every K.O. II has different samples
  loaded, so kobox addresses pads by position and never pretends to know what a
  pad sounds like.
- **It doesn't switch sounds.** On current firmware, MIDI program change doesn't
  change pad sounds — so there's no tool that fakes it.

## Requirements

A Teenage Engineering EP-133 K.O. II, a USB cable, and either Claude Code or `uv`.
Python and the MIDI backend are installed for you during setup.

## License

MIT — see [`LICENSE`](LICENSE).