amaran-mcp

A Model Context Protocol server and CLI through which an AI assistant drives an amaran light from a Mac, built for two uses of equal weight. It works with Claude Code, Cursor, GrokBot and any other MCP client that runs a local server.

Underneath, Apple's on-device sound classifier separates singing from speech, and a 50/50 blend of gradient-boosted trees and a log-mel CNN, trained on 402 expert-labelled Creative Commons EDM tracks, names the section once a second in 3 ms of numpy: balanced accuracy 0.49 on held-out tracks, against 0.36 for hand-written rules. Everything runs on the Mac.

Play a breakdown: press play on a vocal trance track and watch what music mode does, second by second, in step with the music, next to an expert's reading of the same track.

So what · When to use this · How to use this · Music mode · Studio lighting · Tools · What's next · How it reaches the light · Research

So what

Most music-reactive lights flash on every beat. It looks like a club toy, and in a room you work or listen in it wears thin in minutes. Music mode listens the way a musician does instead: it hears the tempo, the chords, the singing and the sections of a track, so the light drifts through the groove, pales when the kick drops out and blooms when a breakdown's chords lift, then opens out at the drop. It never flashes; colour can only change so fast.

Lighting a talking head well is fiddly in the other direction: white balance, tint and level, set by hand and lost by the next call. Here you describe the shot, or show Claude a photo of the set, and it sets the light; a scene brings the same look back tomorrow. Alone in frame, you can say the change out loud instead of getting up to make it.

Everything runs on the Mac: the audio never leaves it, and the light is reached through amaran Desktop or directly over Bluetooth.

When to use this

It is not for stage or club lighting: it drives one light, it is slow by design, and it speaks to amaran lights, not DMX.

How to use this

Set it up once

You need a Mac, uv, Xcode's command line tools (xcode-select --install; music mode compiles its audio helper on first run), and amaran Desktop with the light paired in it.

1. Install the command from PyPI (later, uv tool upgrade amaran-mcp updates it):

   uv tool install amaran-mcp
   

   Without uv, pip install amaran-mcp (Python 3.11 or newer) works too; pip install --upgrade amaran-mcp updates it. For the newest code before a release, install from GitHub instead: uv tool install git+https://github.com/jtannahill/amaran-mcp.

2. Quit amaran Desktop fully (it keeps running after its window closes, and holds the light), then import the light:

   amaran-mcp import
   amaran-mcp status
   

3. Connect your assistant.

   • Claude Code, as a plugin that updates with /plugin update:

     /plugin install amaran --marketplace jtannahill/amaran-mcp
     

     On older versions, /plugin marketplace add jtannahill/amaran-mcp and then /plugin install amaran@amaran-mcp. Or register the command directly: claude mcp add -s user amaran -- amaran-mcp serve.

   • Cursor, in ~/.cursor/mcp.json, with the full path that which amaran-mcp prints (apps opened from the Dock do not see your shell's PATH):

     {
       "mcpServers": {
         "amaran": { "command": "/Users/you/.local/bin/amaran-mcp", "args": ["serve"] }
       }
     }
     

   • GrokBot or any other MCP client: the same command, amaran-mcp serve, by its full path.

4. Ask for something: "warm white at 40 percent", "a slow violet", "start music mode, deep".

To work on the code instead, clone the repo and put uv run before each command.

import writes ~/.config/amaran-mcp/light.json (mode 600; it holds the mesh keys). The first Bluetooth use asks for permission for the app running the command. If the light was paired with the amaran phone app instead, amaran-mcp import --account you@example.com fetches the keys from the amaran account (the password is asked for and never stored; untested).

Then ask for what you want

The same works from the terminal (amaran-mcp music --mood deep, and the other commands under Tools).

Music mode

amaran-mcp music --mood ethereal     # or ask Claude: "start music mode"

The light follows whatever this Mac plays, AirPlay from an iPhone included. It listens to the Mac's own audio output, not a microphone, so headphones are fine. Everything runs on the Mac.

Built for vocal trance

It was tuned on the euphoric, vocal end of trance, the sound of Armin van Buuren's A State of Trance, Find Your Harmony and Future Sound of Egypt, and the genre's habits are built in:

Why this matters for the model, and what the training data lacks: Vocal trance at 138 BPM.

What listens

Apple's classifier is how music mode tells a vocal from a DJ talking over the mix: singing makes a bloom bigger, speech never blooms.

The section model

Two models, blended 50/50:

• Gradient-boosted trees on a 16-second summary of what music mode hears: energy, bass, kick, tempo, harmony, tension, Apple's singing and speech readings, and 11 spectral readings.
• A spectrogram CNN, a small convolutional network that reads the last 16 seconds as a log-mel spectrogram (64 bands, 10 frames a second).

Both learned from SSME: 402 Creative Commons EDM tracks with drops, builds and breaks marked by experts. Training uses scikit-learn and PyTorch; the shipped model is plain numpy arrays (src/amaran_mcp/music/sections.npz), so music mode needs neither. Scored on tracks held out from each model's training (five-fold cross-validation):

Sections is balanced accuracy, the share of seconds called right averaged over the four sections the model names; the others are F scores for finding a start within a few seconds. Rules are the hand-written logic the model replaced. Trance breakdowns are the weakest spot, which is why it also learns from your own listening (below). The full research, every measurement and how to retrain: docs/research.md.

What the light does

Trance gets full colour: saturated blues, violets and orchids that only turn paler at the start of a breakdown, and never grey. Hue turns at most 30 degrees a second, so it never flashes or pulses on the beat.

The same song twice

The sections repeat; the colours do not, on purpose.

Any other light command stops music mode, except brightness, which moves its range. Needs Xcode's command line tools (the audio helper is compiled on first run); macOS asks once for permission to record system audio.

Teaching it your music

amaran-mcp install-listener   # record listening sessions at login
amaran-mcp mark lift          # or breakdown, vocal, build, drop
amaran-mcp uninstall-listener

The listener records while music plays (FLAC, a feature log and your marks, in ~/.config/amaran-mcp/recordings), so a model can be trained on what you actually listen to. It never touches the light, needs ffmpeg, stops at 30 GB, and nothing leaves the Mac. Delete the folder to remove the recordings.

Music mode records the same way when the listener is not running. Either one keeps only the music: a session starts when music is recognised (with the ten seconds before it) and ends two minutes after it stops, so a call or a video afterwards is not kept, and the microphone is never recorded. The folder is readable by your user only.

Studio lighting from a prompt

Interviews and talking heads are mostly white light: the right colour temperature, the right level, no cast on the face, and colour, if any, only on the background. Say what the shot is and Claude sets the light with the same tools:

"Corporate interview, daylight from a window on the left, camera at 5600K. Soft key, a touch warm, not too bright."

"Here's a photo of my set. Light my face for a webcam talk."

Claude reads a photo of the set the way it reads any picture, so it can see the window, the room's colour and where the light sits, and pick the white balance and level from that. Today that is one light; a key, fill and back light setup is planned as more amaran lights join.

Hands free, on camera

Working solo, the light is out of reach once you are in frame: hosting a show alone, or recording a video from the Mac in front of you. Speak to Claude instead, through the Mac's Dictation or the voice input of the Claude app you use, and the light changes while you keep your eyes on the monitor and stay in place:

"Warmer, and down ten percent."

"The sun's gone in. Bring the level up to match."

"Recall interview A."

Each command is an ordinary tool call, so it takes the moment Claude needs to reply: call changes between takes or segments rather than mid-sentence. On a live show the microphone hears the command too, so mute it for the cue or keep cues to the breaks.

Tools

The same from the terminal:

amaran-mcp on | off | status
amaran-mcp brightness 40
amaran-mcp white 3200 60      # kelvin, brightness, optional tint
amaran-mcp color 30 100 50    # hue, saturation, brightness
amaran-mcp effect fire 70
amaran-mcp music --mood deep

Next

Neither of these is built yet.

How it reaches the light

AMARAN_BACKEND=auto (the default) picks one on every call:

Set AMARAN_BACKEND=desktop or bluetooth to force one.

Tested on a PT2c: status, brightness, white, tint, colour, the fire effect and power were each confirmed by the light's own status reports.

Limits

• One light. Custom per-pixel patterns are not supported; the built-in effects are, including the pixel effects through amaran Desktop.
• The light accepts one Bluetooth connection at a time. The auto backend avoids fighting amaran Desktop over it, but a phone app holding it still blocks the Bluetooth backend.
• Through amaran Desktop, the active mode is the last one this server set; a change made in the amaran apps shows only its power and brightness.
• Re-pairing the light in amaran Desktop changes the keys: run import again.

Credits

src/amaran_mcp/sidus/ is vendored unmodified from neyako/amaran-hacs (MIT), which builds on wesbos/amaran-BLE-control. The amaran Desktop message and token format follow bitfocus/companion-module-amaran-desktop (MIT) and the amaran OpenAPI docs. The section model learns from the SSME dataset (Yadati, Larson, Liem and Hanjalic). The demo tracks stream from SoundCloud.