使用说明

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

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:

{
  "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.