mcp-koii

mcp-koii

2
entertainment_and_mediadeveloper_tools

This project provides an MCP server for the Teenage Engineering EP-133 K.O. II sampler, allowing control via MIDI using text commands. It supports integration with Claude and offers features like creating drum patterns and simultaneous instrument playback.

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

This project is a Model Context Protocol (MCP) server that acts as a controller for the Teenage Engineering EP-133 K.O. II sampler via MIDI

Features

  • Connect to your EP-133 K.O. II device via MIDI
  • Play notes and patterns through text commands
  • View the default pad configuration to understand sound mapping
  • Create and play drum patterns with a simple text-based syntax
  • Support for multiple instrument reference methods (pad labels, MIDI notes, instrument names, sound names)
  • Simultaneous playback of multiple instruments in drum patterns
  • Integration with Claude through MCP

Installation

Prerequisites

  • Python 3.8 or later
  • mido (MIDI handling)
  • mcp (Model Context Protocol SDK)

Quick Install

# Install the required packages
pip install mido "mcp[cli]"

# Clone the repository
git clone https://github.com/benjaminr/mcp-koii.git
cd mcp-koii

# Install the MCP server
mcp install koii_server.py:server -e .

Usage with Claude Desktop

  1. Make sure your EP-133 K.O. II is connected to your computer via USB.

  2. Launch Claude Desktop with MCP enabled.

  3. Start controlling your EP-133 K.O. II by asking Claude natural language questions like:

    • "List available MIDI ports"
    • "Connect to the EP-133 device"
    • "Play a C major scale"
    • "Play a drum pattern with kick on beats 1 and 3, snare on 2 and 4, and hi-hat on every 8th note"

Running in Development Mode

You can run the MCP server in development mode to test it without Claude Desktop:

# Run with the inspector UI
mcp dev koii_server.py:server -e .

Features and Commands

Basic Commands

  • List available MIDI ports: Shows all available MIDI output ports on your system.
  • Connect to a MIDI device: Connect to the EP-133 K.O. II by name or port number.
  • Disconnect: Close the connection to the current MIDI device.

Playing Notes and Patterns

  • Play a note: Play a single note with specified velocity and duration.
  • Play a pattern: Play a sequence of notes with timing information.
  • Play a drum pattern: Play a text-based drum pattern.

Sound Browser

  • List sound categories: View available sound categories (Kicks, Snares, etc.).
  • List sounds in category: Browse sounds within a specific category.
  • Get default pad configuration: See which sounds are mapped to each pad by default.

MIDI Implementation

The EP-133 K.O. II responds to the following MIDI messages:

  • Note On/Off: Triggers sounds on pads (C2-B5, notes 36-83)

Drum Pattern Syntax

The drum pattern system supports four different ways to reference sounds:

1. Using pad references:

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

2. Using MIDI note numbers:

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

3. Using sound names:

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

4. Mixed references:

x...x...x...x...  # A.       (pad reference)
....x.......x...  # 40       (MIDI note)
......x.........  # "NT RIDE" (sound name)

Pattern Format

  • Each line represents a different instrument/sound
  • 'x' or 'X' indicates a hit (high velocity)
  • 'o' or 'O' indicates a softer hit (lower velocity)
  • '.' indicates no hit
  • Each position represents a 16th note
  • Comments after '#' specify what sound to trigger using any of the reference methods
  • Multiple instruments can be triggered simultaneously with their hits overlapping

Troubleshooting

  • No MIDI ports found: Make sure your EP-133 K.O. II is connected and powered on.
  • Connection issues: Try reconnecting the USB cable or restarting your EP-133.
  • Notes not playing: Verify that the device is in the correct MIDI mode.
  • Multiple instruments not playing simultaneously: Use a higher BPM value to ensure the EP-133 K.O. II can process all notes during playback.
  • Unknown instruments: Use exact instrument names, pad labels, MIDI notes or sound names in quotes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments