Halo PixelBar MCP

A local MCP server for controlling an EDIFIER Halo PixelBar from an AI on Windows. It exposes a small allowlist for the ambient light, pixel screen, and the speaker's independent hardware volume.

This is an independent community project. It is not affiliated with, endorsed by, or supported by EDIFIER.

See PROTOCOL_NOTES.md for the observed packet format, field mappings, and live hardware tests.

Prerequisites

• Windows 10 or Windows 11.
• An EDIFIER Halo PixelBar (花再) exposing USB VID 0x2D99, PID 0xA106, HID interface 4, usage page 0xFF14, and usage 1.
• A USB connection that carries data, not a power-only cable. A data-capable adapter or dock is fine when Windows can enumerate the HID interface.
• Python 3.11 or newer.
• A local MCP host that can launch a stdio server, such as Codex or Claude Desktop.

EDIFIER TempoHub was installed while the protocol was validated, but this MCP does not call TempoHub, read an EDIFIER account, or require account credentials. The device filter is intentionally strict; other EDIFIER speakers and PixelBar revisions are not assumed to be compatible.

Install

git clone https://github.com/Seraph310/halo-pixelbar-mcp.git
cd halo-pixelbar-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Codex configuration

Add the following to %USERPROFILE%\.codex\config.toml, replacing both paths:

[mcp_servers.halo_pixelbar]
command = 'C:\path\to\halo-pixelbar-mcp\.venv\Scripts\python.exe'
args = ['C:\path\to\halo-pixelbar-mcp\server.py']
startup_timeout_sec = 30

Restart the MCP host after changing its configuration.

Tools

Tool	Purpose
get_halo_status	Detect the validated HID control interface
get_halo_volume	Read the independent 0-16 speaker volume
set_halo_volume	Set the hardware volume and verify it by querying again
show_halo_text	Display a short UTF-8 message with a safe layout
set_halo_scene	Select a built-in clock, game, work, reading, pet, meme, cyber, or waveform scene
set_halo_screen_color	Set the pixel-screen theme color
set_halo_ambient	Set light effect, RGB color, brightness, and speed
set_halo_ambient_power	Switch only the ambient light on or off

Tested environment

• Windows 11 64-bit, build 26200.
• EDIFIER Halo PixelBar (花再), USB VID 0x2D99, PID 0xA106.
• EDIFIER TempoHub installer version 1.2.6.
• Python 3.11.5.
• A data-capable USB adapter; a direct motherboard connection is not required when Windows can still enumerate the HID interface.

Safety boundary

• Targets only the exact validated VID, PID, interface, usage page, usage, and a matching Halo/PixelBar product name.
• Exposes no arbitrary HID packet, firmware, factory-reset, account, file, or shell-command tool.
• Validates colors, scenes, effects, speed, brightness, layouts, text length, and hardware volume before writing.
• Does not require or read EDIFIER TempoHub credentials.
• Omits the physical device serial number from public MCP status results.

Optional music companion

Pair this server with CloudMusic Desktop MCP to let an MCP host coordinate AI-selected music with light, screen, and hardware-volume changes. The two servers are independent and can be installed separately.

Protocol attribution

The packet format was established through local device observation, the installed official controller, and live readback tests. It was also compared with the MIT-licensed XFEstudio/HaloPixelToolBox implementation and the official Halo PixelBar user manual. No extracted TempoHub binaries, decompiled files, credentials, firmware, or research snapshots are included in this repository.

Test

.\.venv\Scripts\python.exe -m pytest -q

Credits

Built together by Celia and OpenAI Codex.

Celia led the product direction and live hardware validation. Codex assisted with reverse engineering, implementation, and testing.

License

MIT