# midi-mcp

MCP server that lets Claude control electronic music instruments via MIDI. Exposes tools for sending MIDI messages (notes, CC, program changes, pitch bend, sysex) to hardware synths and drum machines connected via USB or DIN MIDI.

## Setup

Requires [uv](https://docs.astral.sh/uv/).

```bash
cd midi-mcp
uv sync
```

## Usage

### Add to Claude Code

```bash
claude mcp add midi-mcp -- uv --directory /path/to/midi-mcp run midi-mcp
```

Or add manually to your MCP config:

```json
{
  "mcpServers": {
    "midi-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/midi-mcp", "run", "midi-mcp"]
    }
  }
}
```

### Run standalone

```bash
uv run midi-mcp
```

## Tools

| Tool | Description |
|------|-------------|
| `list_midi_ports` | List available MIDI output ports |
| `open_midi_port` | Open a specific MIDI output port by name |
| `close_midi_port` | Close the currently open port |
| `get_midi_status` | Return current port name and connection state |
| `send_note_on` | Send Note On (channel, note, velocity) |
| `send_note_off` | Send Note Off (channel, note, velocity) |
| `send_cc` | Send Control Change (channel, control, value) |
| `send_program_change` | Send Program Change (channel, program) |
| `send_pitchwheel` | Send Pitch Bend (channel, value) |
| `send_sysex` | Send SysEx message (list of data bytes) |

## Dependencies

- [mcp[cli]](https://pypi.org/project/mcp/) - MCP Python SDK with FastMCP
- [mido](https://mido.readthedocs.io/) - MIDI message library
- [python-rtmidi](https://pypi.org/project/python-rtmidi/) - Real-time MIDI I/O backend