HXAudio MCP

简体中文 · Architecture · License

Control HXAudio APO directly from an AI agent. HXAudio MCP is a local Model Context Protocol (MCP) server for reading and adjusting Windows HXAudio parametric EQ, preamp, and virtual bass settings—without automating the graphical interface.

The server communicates over stdio and applies supported changes through the Windows registry with HXAudio's live-reload notification mechanism.

Features

• Parametric EQ: list, replace, add, update, and remove filters for individual audio devices.

• Audio controls: adjust preamp and virtual bass; inspect other available DSP settings.

• Live updates: apply changes and inspect APO runtime status.

• Preset management: back up and restore DSP settings; inspect and import PEQ curves from .hxconfig files.

• Agent-friendly: structured MCP tools, an optional EQ workflow skill, and read-only mode.

Related MCP server: room-eq-wizard-mcp

Requirements

• Windows 10 or 11 with HXAudio APO installed and configured.

• Python 3.11+.

• An MCP-compatible client running on the same Windows computer.

• Permission to modify HXAudio registry settings. APO mode typically requires administrator privileges for system-level writes.

Installation

Open PowerShell in the repository directory:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Confirm that HXAudio is detected:

hxaudio-mcp doctor
hxaudio-mcp devices
hxaudio-mcp eq

Note: hxaudio-mcp serve starts a stdio server and is intended to be launched by your MCP client; it does not open a web page or interactive shell.

MCP client configuration

Use the absolute path to the executable in your virtual environment. Replace the sample path with your own installation directory.

Codex

Add the following to ~/.codex/config.toml:

[mcp_servers.hxaudio]
command = 'C:\path\to\hxaudio-mcp\.venv\Scripts\hxaudio-mcp.exe'
args = ['serve']
startup_timeout_sec = 20
tool_timeout_sec = 30

Alternatively, register it using the Codex CLI:

codex mcp add hxaudio -- "C:\path\to\hxaudio-mcp\.venv\Scripts\hxaudio-mcp.exe" serve

Clients using mcpServers JSON

For clients that accept the mcpServers configuration format:

{
  "mcpServers": {
    "hxaudio": {
      "command": "C:\\path\\to\\hxaudio-mcp\\.venv\\Scripts\\hxaudio-mcp.exe",
      "args": ["serve"]
    }
  }
}

The client launches the server locally. For APO write operations, the server process must have the required Windows registry permissions; these are inherited from the MCP client process.

Available tools

PEQ filter format

Filters use five fields:

{
  "enabled": true,
  "type": "PK",
  "frequency_hz": 1000,
  "gain_db": -2.5,
  "q": 1.0
}

Supported types: PK (peak), LS (low shelf), HS (high shelf), LP (low pass), HP (high pass), and NO (notch). Band indices are zero-based.

set_eq replaces the entire list. Use update_eq_band to change one filter while keeping the others. When multiple devices are available, pass the exact profile_key obtained from list_audio_devices.

Example agent requests

Show the EQ settings for my speakers and create a backup.

Set the first PEQ filter's gain to −2 dB, leaving its frequency and Q unchanged.

Add a peak filter at 250 Hz with a gain of −1.5 dB and Q of 1.2, then show the updated curve.

Import the PEQ curve from C:\Users\me\Music\preset.hxconfig into my selected output device.

Configuration and usage notes

• Read-only mode: set HXAUDIO_MCP_READ_ONLY=1 in the MCP client's environment to disable write operations.

• Backups: stored under %LOCALAPPDATA%\HXAudioMCP\backups; restore_eq_backup requires the returned backup ID and confirm=true.

• HXAudio GUI: the EQ editor can remain open while the MCP server applies changes. Avoid saving an older GUI state over newer MCP changes (or vice versa).

• Audio headroom: positive EQ gains can increase output level; adjust preamp as appropriate.

• Local operation: the stdio server does not expose an HTTP endpoint. It works with settings on the computer where it runs.

For the registry integration and project structure, see Architecture.

License

MIT. HXAudio MCP is an independent integration project and is not affiliated with the HXAudio developer. HXAudio itself is not included in this repository.