fh2-mcp
MCP server for controlling an Expert Sleepers FH-2 MIDI-to-CV Eurorack module over USB MIDI.
Provides 38 tools for direct CV output control, LFO configuration, display/panel remote control, preset and configuration management, tuning, and standard MIDI messaging.
Part of the Expert Sleepers MCP suite:
fh2-mcp |
es9-mcp |
disting-nt-mcp |
es-orchestrator-mcp
Requirements
- Python 3.11+
- uv package manager
- Expert Sleepers FH-2 connected via USB
Setup```bash
git clone https://github.com/Ziforge/fh2-mcp.git
cd fh2-mcp
uv sync
cp .env.example .env # edit with your MIDI port names
### Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `FH2_OUTPUT_PORT` | `FH-2` | MIDI output port (substring match) |
| `FH2_INPUT_PORT` | `FH-2` | MIDI input port (substring match) |
| `FH2_MIDI_CHANNEL` | `1` | MIDI channel for CC control (1-16) |
| `FH2_AUTO_CONNECT` | `true` | Connect on server start |
### Claude Desktop
Add to `claude_desktop_config.json`:```json
{
"mcpServers": {
"fh2": {
"command": "uv",
"args": ["run", "--directory", "/path/to/fh2-mcp", "python", "server.py"]
}
}
}
Tools (38)
Connection (3)
| Tool | Description |
|---|---|
connect_fh2 |
Connect to FH-2 MIDI ports (auto-detects if empty) |
disconnect_fh2 |
Disconnect from FH-2 MIDI ports |
list_midi_ports |
List all available MIDI I/O ports |
CV Output (4)
| Tool | Description |
|---|---|
set_cv_output |
Set a CV output (1-8) via MIDI CC |
set_cv_voltage |
Set a CV output by target voltage |
set_all_cv |
Set all 8 CV outputs at once |
zero_all_cv |
Reset all CV outputs to 0 |
LFO Control (3)
| Tool | Description |
|---|---|
configure_lfo |
Set multiple LFO parameters at once |
set_lfo_param |
Set a single LFO parameter |
reset_lfo |
Zero all parameters for a given LFO |
Display & Panel (5)
| Tool | Description |
|---|---|
read_display |
Read the FH-2 4-line OLED display text |
take_screenshot |
Capture the 128x32 OLED as ASCII art |
display_message |
Show a text message on the OLED |
panel_press |
Send a virtual encoder/button event |
navigate_menu |
Send a sequence of panel events with delays |
Configuration & Presets (9)
| Tool | Description |
|---|---|
get_config_name |
Get current configuration name |
download_config |
Request full configuration dump |
upload_config |
Install configuration from a .syx file |
get_preset_name |
Get current preset name |
download_preset |
Request full preset dump |
save_preset |
Save current state to flash |
get_clock_info |
Request clock/tempo info |
install_scala |
Upload a Scala tuning file |
install_kbm |
Upload a keyboard mapping file |
MIDI Messaging (5)
| Tool | Description |
|---|---|
send_note |
Send Note On/Off on a MIDI channel |
send_cc |
Send a MIDI CC message |
send_chord |
Send multiple notes simultaneously |
send_pitch_bend |
Send 14-bit pitch bend |
send_program_change |
Send Program Change with optional bank select |
MIDI Monitoring (3)
| Tool | Description |
|---|---|
start_midi_monitor |
Start logging incoming MIDI messages |
stop_midi_monitor |
Stop logging |
get_midi_log |
Get recent messages from the log |
SysEx (3)
| Tool | Description |
|---|---|
send_sysex |
Send a raw SysEx message |
receive_sysex |
Listen for a single incoming SysEx |
send_raw |
Send raw MIDI bytes directly |
Safety & Status (2)
| Tool | Description |
|---|---|
all_notes_off |
Send All Notes Off (CC#123) |
midi_panic |
Emergency panic — silence everything |
query_status |
Full server status report |
Architecture```
server.py — FastMCP tool definitions (38 tools)
engine.py — FH2Engine: MIDI connection + SysEx protocol
protocol.py — FH-2 SysEx command encoding/decoding
config.py — Configuration from environment
```
Note
When using the es-orchestrator-mcp, stop this server — macOS cannot share MIDI output ports between processes.
