Skip to main content
Glama

oxi-mcp

An MCP server for the OXI ONE MKII sequencer. It lets an AI assistant (Claude Code, Claude Desktop, or any MCP client) drive the OXI over USB MIDI, and take over its pads, button LEDs and OLED screen through the device's SysEx remote mode.

Unofficial; not affiliated with OXI Instruments.

Status: early. The protocol bytes are tested against the examples in OXI's own reference sheet, and every tool is tested through a fake MIDI port. Hardware testing is in progress, so expect fixes: see Not yet verified on hardware.

Install

git clone https://github.com/nkorai/oxi-mcp && cd oxi-mcp
pip install -e .
claude mcp add --scope user oxi-one -- python -m oxi_mcp.server      # Claude Code
python -m unittest                                                    # tests, no device needed

Claude Desktop / other clients: run python -m oxi_mcp.server (stdio) or the oxi-mcp script.

Connect the OXI over USB in device mode (manual p.261). On Windows only one app can hold a MIDI port at a time, so close anything else that has the OXI open. oxi_connect(port_hint=...) picks other ports, e.g. a loopMIDI port for testing without the device.

Related MCP server: X32/M32 MCP Server

Tools

area

tools

basis

connection

oxi_status (ports, firmware probe), oxi_connect, oxi_disconnect

plain MIDI

oxi_transport, oxi_clock (24 ppqn from a background thread), oxi_select_column (Program Change), oxi_send_note, oxi_send_cc

MKII manual: sync p.265, PC column select p.240, transpose p.68, MIDI capture p.93

remote mode

oxi_remote, oxi_grid, oxi_led, oxi_led_names, oxi_oled (text, with PNG preview), oxi_events (pads, buttons, encoders)

OXI Remote Control Reference sheet, MKII tab (linked from manual p.273)

raw

oxi_sysex (refuses firmware-update / memory-reset / project send+delete unless allow_destructive=True), oxi_probe_project

experimental: MK1 desktop-app protocol

projects (optional)

oxi_projects, oxi_pattern, oxi_show_pattern (draw a pattern on the pads), oxi_edit_pattern

needs RACK_LIBRARY, below

device projects

oxi_device_projects (the 20 internal slots), oxi_device_push (library project -> a slot over USB; refuses a used slot unless overwrite=True)

MK1 project SysEx, measured working on the MKII 2026-11-02

SD card

oxi_card (what's on the card vs the library), oxi_card_pull (card -> library), oxi_export (library -> card)

MKII manual p.23, p.277; decoding needs RACK_LIBRARY

Things to ask for: "show 'HELLO' on the OXI screen", "light the grid as a VU meter", "run clock at 128 and start", "jump to pattern column 3", "tell me which pads I press".

Optional: project files

The project tools read and edit .oxipro projects kept in a rack-library-style checkout (projects/<slug>/ with the .oxipro, project.md and patterns.json; edits go through its tools/serve.py save path and are committed with git). Set RACK_LIBRARY to the checkout to enable them:

claude mcp add --scope user oxi-one -e RACK_LIBRARY=/path/to/rack-library -- python -m oxi_mcp.server

Without it those tools return an error and everything else works.

The SD card wins

Projects are played and saved on the OXI, so the microSD card is the source of truth. With the card in a reader, the tools find it by the folders the OXI creates at power-up (Projects, Settings, Instruments, Grooves, Scales); pass card_path or set OXI_CARD if it is somewhere else.

  • oxi_card lists the card's projects and says whether each is the same as the library's copy, differs, or is new.

  • oxi_card_pull takes the card's version into the library (notes in project.md are kept; git keeps the old file).

  • oxi_edit_pattern on a project that is on the card pulls the card's version first, edits it, and writes it back to the card, refusing if the card changed in between. on_card=False edits only the library.

  • oxi_export copies a library project onto the card. A card file that differs is kept unless you tell it to overwrite (overwrite=True), which replaces the card's version with the library's.

The OXI keeps projects in 20 internal slots; a project reaches the card only through Project menu (Shift + Perf) > Copy to SD Card, and comes back through Load from SD Card (manual p.23).

Protocol notes

  • SysEx header MKII F0 00 21 5B 01 01 (MK1 .. 00 01). Values after the category byte are nibbled (high, low).

  • Remote mode: enter 06 55 -> ACK 06 53; exit 00; pad 01 id r g b; button LED 02 id value (off 0, on 1, blink 2, blink fast 4, short 6); OLED 03 + 1024 bytes (128x64, 1 bit per pixel).

  • Pad id = x + 16*y on 16 columns x 8 rows. The sheet's text says x 0-7 / y 0-15, but its "row 2 col 4" example (id 0x13) only fits 16x8; the tests encode both of its examples byte for byte.

  • Events in remote mode: pads = notes on ch 1 (x + 16y), function buttons = notes on ch 2 (FunctionButtons_e order), encoders = CC on ch 1, value 1-8 clockwise / 0x11-0x18 counter-clockwise.

Not yet verified on hardware

  • The remote-mode ACK and event decoding.

  • OLED pixel packing: undocumented. oxi_oled(layout="pages") is SSD1306-style; try "rows" if text is scrambled.

  • SYSTEM version (03 00) comes from the MK1 desktop app and may not exist on MKII.

  • PROJECT (05 ..) transfer works on the MKII (measured 2026-11-02): get/send header 05 00/05 01 and pattern 05 02/05 03 per slot (0-19) and pattern (seq*16+pat), data 7-bit packed (a high-bits byte, then 7 bytes), ACK 05 53, NACK 05 54. Current firmware stores headers as version 12 (0x2A44 bytes) and converts a sent version-10 header itself. Windows delivers long SysEx in 1024-byte pieces; device.py joins them.

Reports from MKII owners are welcome: open an issue with your firmware version and what you saw.

Prior art

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers