headrush-mcp
A local MCP server for inspecting and editing a HeadRush Flex Prime pedal over your home network.
Read pedal status, firmware, loaded rig, DSP load, rigs, setlists, routings, blocks, block parameters/presets, footswitches, scenes, and global footswitch settings.
Search blocks, models, and installed files by name or inspired-by gear using
find_models.Inspect the loaded rig's chain, routing, parallel mix, scenes, and footswitch assignments, including warnings about unreachable switches.
With
HEADRUSH_ALLOW_WRITES=1, change block parameters/slots, routing, mix, footswitches, and scenes; activate scenes, load rigs, save rigs, and build new rigs from specs.Safety limits: writes are off by default; unsaved-edit checks apply; rig creation verifies read-back before saving; deleting/renaming rigs, setlist changes, cloud actions, and MIDI output are not supported.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@headrush-mcp what rig is loaded on my HeadRush?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
# headrush-mcp
A local MCP server for the HeadRush Flex Prime. It lets an AI assistant on your computer inspect your pedal and build rigs: chains, parallel amps, scenes and footswitches.
It talks to the Remote Editor built into the pedal, over your home network. It runs as a stdio subprocess of your MCP client, with no cloud service and no network port of its own.
Unofficial. The pedal's API is undocumented and was worked out from the editor's own traffic, so firmware updates may break this. It's only been tested on a Flex Prime running firmware
5.2.0.2a405ee. Other models may differ. Not affiliated with HeadRush or inMusic.
Models: the Flex Prime is the only model tested. The Core and Prime run the same HeadRush Remote API from firmware 4.0, but they have different footswitch counts, so they're untested here and footswitch tools may not fit them. The Pedalboard, Gigboard and MX5 have no HeadRush Remote and aren't supported.
Requirements
A HeadRush Flex Prime on firmware 4.0 or later (current firmware recommended), on Wi-Fi, with Global Settings > HeadRush Remote turned on
A computer on the same network
An MCP client that supports stdio servers, such as Claude Code or Claude Desktop
Related MCP server: keenetic
Setup
Get the code and install it:
git clone https://github.com/Haervwe/headrush-mcp.git cd headrush-mcp uv syncCheck the pedal is reachable. Open
http://headrushflexprime.localin a browser, and you should see the Remote Editor. If not, use the IP shown on the pedal under Menu → Global Settings.Add the server to your MCP client's config, using the full path to this folder:
{ "mcpServers": { "headrush": { "command": "uv", "args": ["run", "--directory", "/path/to/headrush-mcp", "headrush-mcp"], "env": { "HEADRUSH_HOST": "headrushflexprime.local", "HEADRUSH_ALLOW_WRITES": "0" } } } }Restart your client and ask it something like "what rig is loaded on my HeadRush?"
Settings
Variable | Default | Purpose |
|
| The pedal's hostname or IP. An IP avoids mDNS lookups, but use a DHCP reservation so it doesn't change |
| off | Set to |
Tools
Read:
Tool | What it does |
| Firmware, loaded rig, unsaved-edit flag, DSP load |
| Browse your library |
| Loaded rig's routing, mix and chain |
| Footswitch summary |
| One scene's blocks, A/B doubling, path, presets and color, including a second state if it has one |
| What a footswitch can control: modules and their operations |
| Global tuner, looper and auto-assign settings |
| The |
| Search blocks, models and installed files by name or by the gear they're inspired by (details) |
| Available blocks and their presets |
| A block's values, as 0-1 or as shown on the pedal, and its parameter schema |
| Signal routings and their slot layouts |
Write (needs HEADRUSH_ALLOW_WRITES=1):
Tool | What it does | Saved? |
| Edit blocks, in 0-1 or real units, and the chain | No |
| Change routing and parallel mixing | No |
| Assign footswitches and scenes, including a scene's second state | No |
| Fire a scene | No |
| Switch rigs | No |
| Build, verify and save a rig from a spec | Yes, as a new rig |
| Save under a new name | Yes, as a new rig |
| Overwrite the loaded rig's saved copy | Yes, overwrites |
Finding models
Block names don't always say what they are, so find_models lets your assistant search by real gear. "Klon" finds K Drive, and "twin" finds the 67 Black Duo amp. It combines two sources:
A shipped catalog covers blocks and built-in and ReValver amps, cabs and mics. Categories come from the pedal. What each model is inspired by comes from Headrush Help, a free community reference by Stefano Luciani and Donato Iacoviello, which also explains each block's controls. Those links are community research, not official information, and aren't endorsed by HeadRush or the gear's makers.
Your pedal provides what's installed and each option's index, along with your clone, NAM, IR and reverb files.
Anything the catalog doesn't know, like a capture from Tone3000, is still listed, but with inspired_by empty. Files are only identified by name, so name them well if you want to search for them. If the pedal isn't reachable, the catalog still answers, with installed unknown.
Safety
Write tools change the pedal immediately, so a rig can change while you're playing, and new settings can be loud. Keep your volume down when trying something new.
Writes are off until you enable them.
Only allowlisted device calls are possible. Deleting and renaming rigs, setlist changes and cloud actions aren't available, so do those on the pedal or in the Remote Editor.
load_rigandcreate_rigare refused if the loaded rig has unsaved edits. The pedal doesn't flag edits made over its API, so the server also remembers its own until you save or load a rig. It forgets them when it restarts. Edits made on the pedal itself aren't flagged either (Flex Prime, firmware 5.2), so save those before asking your assistant to load or create a rig.save_rig_as_newandcreate_rigare refused if the name already exists.Those checks refuse if the pedal doesn't report what they need, such as after a firmware change.
A new rig only counts as saved once the pedal lists it.
Each tool tells your MCP client whether it's read-only or can replace something, for clients that use those hints.
save_loaded_rigis the only way to overwrite a rig, and it must be given the loaded rig's exact name.Values are checked against the pedal's own schema before writing.
set_slot_blockandcreate_rigrefuse blocks that the pedal lists but has no object for, likeReValver Amp 2on current firmware. Writing one of those crashed a Core's audio engine in a community test.create_rigonly saves if every value reads back correctly. The pedal is reported to snap values to each parameter's step size (community, tested on a Core), so a read-back within one step counts as correct.
Stay on a trusted network. The pedal's API is plain HTTP. No login was needed on the tested pedal, and Authorize with PIN is something you turn on, so it's probably off by default. Anything on your network can likely reach it, with or without this server. Don't expose it or this server to the internet. Treat text from rig names and other device data as untrusted input to your assistant.
Good to know
Footswitch banks: switches 1-3 and 4-6 are the two banks, and software can't tell which one the pedal is showing. The tested pedal starts on 4-6, and 1-3 need a hold set to Bank A/B, so see Reaching both banks. Put what you use most on the same bank.
Auto-assign: with Auto Assign Footswitches on in Global Settings, the pedal gives each newly placed block the next free switch.
set_slot_blockandcreate_rigwarn when that may take a switch, andget_footswitchesreports the setting.Numbers are normalized by default: parameters are 0-1 on the wire. Pass
display=truetoget_block,set_block_paramsorset_mixto use the units the pedal shows, like -3 for -3.0 dB, ordisplay_paramsin a rig spec. See the API reference for the conversions.Second instances: names ending in
2, likeAmp 2, let the same block type appear twice. They're how you run two amps.Hearing the result: the server can verify settings, but not sound, so you'll be the judge.
MIDI: the pedal can also be controlled with MIDI CC messages from a MIDI controller. This server doesn't send MIDI, but docs/midi.md lists what's available.
Reaching both banks
The Flex Prime has three switches and two banks of three assignments per rig. Only one bank is available until a hold is set to Bank A/B. On the tested Flex Prime that's switches 4-6, so 1-3 are the ones behind the hold. To use both, on the pedal:
Go to Global Settings > General.
Set Assign Tuner Footswitch (the hold function of switch 3) or Assign Looper Footswitch (the hold of switch 2) to Bank A/B.
Check that Footswitch Function is On Release. On Press disables hold functions, so you can't change banks.
Now hold that switch to flip between banks, live or while editing in Hardware Assign. The trade-off is losing hold-for-tuner or hold-for-looper on that switch. The tuner is still in the menu, and Global Settings > Expression Pedal can open it when a volume pedal reaches 0%. MIDI CC 20 also flips the bank. These settings affect every rig, and this server only reads them.
get_footswitches warns when switches 1-3 are assigned but can't be reached, or when On Press has disabled holds. They're left out when the settings can't be read or their options aren't named.
Example rigs
Starting points in rigs/, to adapt with your own ears:
Spec | What it is |
Mike Stern-inspired detune, delay and overdrive on two parallel amps, with scenes (notes) | |
The same idea on one amp, using about half the DSP | |
Pat Metheny-inspired guitar synth over a 14/26 ms split (notes) |
To try one, ask your assistant to create_rig with the file's full path.
Troubleshooting
Problem | Try |
Can't connect | Open the editor in a browser. If |
Error 403 | HeadRush Remote is probably off (community reports from a Core). Turn it on under Global Settings > HeadRush Remote |
Error 401, or the pedal shows a PIN | Authorize with PIN is on (firmware 5.0 and later). This server can't pair. Approve the connection on the pedal if it offers that, or turn Authorize with PIN off while you use it |
"Writes are disabled" | Set |
"Has unsaved edits" | Save or discard them on the pedal first |
"Unsaved edits made through this server" | Save them with |
| Nothing was saved. Retry with |
| It only reuses a draft this server built since it started, so a draft from before a restart, or your own, is left alone. Discard the draft on the pedal, then run |
"Didn't confirm saving" | The pedal didn't list the new name in time. Check |
Can't reach one bank of switches | Changing banks needs a hold set to Bank A/B. See Reaching both banks |
A block took a footswitch you didn't assign | Auto Assign Footswitches is on. Reassign it, or turn the setting off on the pedal |
A value reads back slightly different | The pedal is reported to snap to the parameter's step size (community, Core). A difference within one step is normal |
Development
uv run pytestTests use a simulated pedal and don't touch your network. See docs/api.md for what's known about the pedal's API, and AGENTS.md for rules when changing this code.
Limitations
State is read over REST. The pedal's WebSocket push isn't used yet.
A rig can only be inspected once it's loaded, because no read-only way to fetch an unloaded rig has been found.
Toggle footswitches and scenes with one or two states are tested on a Flex Prime on firmware 5.2.
activate_scenefires a two-state scene's current state but doesn't alternate to the other one, so reaching the second state takes a press on the pedal. MIDI out can't be set, and the active A/B side can't be read.The catalog was built for firmware
5.2.0.2a405ee, and writing a clone, NAM, IR or reverb file to a block hasn't been tested yet.
Thanks
To Stefano Luciani and Donato Iacoviello for Headrush Help. Their research is the source of the catalog's "inspired by" information, and their site is the place to learn what each block's controls do. They aren't involved with this project.
License
Available Tools
28 toolsactivate_sceneADestructive
Fire the scene on footswitch 1-6 of the loaded rig, without saving.
On a two-state scene this applies the current state. It doesn't alternate to the other state, which takes a press on the pedal.
Inputs: switch (required). Returns: object
create_rigA
Build a new rig from a spec, verify it, and save it only if everything matches.
Pass spec or a local JSON spec_path; get_rig_spec_format has the format, including
scenes. Unknown keys are refused. Refused if the name exists, the loaded rig has unsaved
edits, or a block has no object on the pedal (such as ReValver Amp 2 and C-Verb 2). If a
build fails, retry with resume_draft to reuse the unnamed draft it left, which
overwrites that draft. That only works for a draft this server built since it started.
saved is only true once the pedal lists the new rig.
Numbers count as matching within one step of the parameter's grid, since the pedal snaps
to it. Check warnings: with Auto Assign Footswitches on, the pedal may have put new
blocks on switches the spec didn't set.
Inputs: save, spec, spec_path, resume_draft. Returns: object
describe_blockBRead-only
Read a block's parameter schema: types, display ranges and options.
Inputs: block (required). Returns: object
find_modelsARead-only
Find blocks, models and files by name or by the gear they're inspired by.
query matches words, like "klon", "twin" or "ac30". kind is one of block, amp, cab,
mic, clone, superclone, nam, ir or reverb; ir and reverb are only searched when asked for.
category filters blocks, like "overdrive".
installed is true, false, or null if the pedal couldn't be checked. For a model, write
index to param on block, or its name when using displayed units. For a file, write file to param on one of blocks.
Trust inspired_by only as far as notes says, and never guess it for an unknown model.
Inputs: kind, limit, query, category. Returns: object
get_blockARead-only
Read a block's current values. Numbers are normalized 0-1.
With display, values read as on the pedal, like "-3.0 dB", and options by name. A number
with an unknown curve stays 0-1.
Inputs: block (required), display. Returns: object
get_current_rigARead-only
Get the loaded rig's name, routing, parallel mix and block chain.
Inputs: no named parameters. Returns: object
get_footswitchesARead-only
Summarise footswitches, with warnings about switches you can't reach.
Switches 1-3 and 4-6 are separate banks. The pedal starts on 4-6, and 1-3 are only reachable
by holding a switch whose hold function is Bank A/B. Holds don't work with Footswitch
Function set to On Press. warnings says when either gets in the way.
auto_assign_footswitches is whether the pedal puts newly placed blocks on free switches,
or null if settings couldn't be read.
Scene switches show doubling and path; use get_scene for the rest. The pedal keeps an old module and operation on scene switches, so those only appear on toggle and hold switches.
Inputs: no named parameters. Returns: object
get_footswitch_settingsARead-only
Read global settings that affect every rig: tuner and looper switch behaviour and more.
This server can't change them, so do that on the pedal.
Inputs: no named parameters. Returns: object
get_rig_spec_formatBRead-only
Get the create_rig spec format, including footswitches, scenes and routings.
Inputs: no named parameters. Returns: result
get_sceneARead-only
Read a scene on footswitch 1-6: blocks, doubling, path, presets, color and MIDI out.
Uses the same shape as set_scene. When states is 2, each press alternates between two
states: the top-level fields are the first, second_state holds the second, and
current_state is 1 or 2. The pedal doesn't report which A/B side is active.
Inputs: switch (required). Returns: object
get_setlistCRead-only
Read one setlist.
Inputs: setlist_id (required).
get_statusARead-only
Get firmware, loaded rig, unsaved-edit flag and DSP load.
Inputs: no named parameters. Returns: object
list_block_presetsCRead-only
List a block's factory and user presets.
Inputs: block (required). Returns: result
list_blocksARead-only
List block names usable in a chain slot. Names ending in ' 2' are second instances.
Inputs: no named parameters. Returns: result
list_footswitch_actionsARead-only
List what footswitch 1-6 can control, for choosing set_footswitch's arguments.
Without module, returns the modules the switch can be assigned. With one, returns its
operations; those with enabled false can't be chosen right now. MIDI Out is listed by
the pedal but can't be assigned here.
Inputs: switch (required), module. Returns: object
list_rigsARead-only
List every rig on the pedal with its id.
Inputs: no named parameters. Returns: result
list_routingsBRead-only
List signal routings and which chain slots belong to each section.
Inputs: no named parameters. Returns: result
list_setlistsARead-only
List setlists with their ids and rig counts.
Inputs: no named parameters. Returns: result
load_rigB
Load a rig by id. Refused if the current rig has unsaved edits.
Inputs: rig_id (required), sr_id. Returns: object
remove_scene_second_stateBDestructiveIdempotent
Go back to one state on the scene on footswitch 1-6, without saving.
Inputs: switch (required). Returns: object
save_loaded_rigADestructiveIdempotent
Overwrite the loaded rig's saved copy. Refused unless the exact loaded name is given.
Inputs: expected_name (required). Returns: object
save_rig_as_newA
Save the loaded rig under a new name. Refused if the name already exists.
Inputs: name (required). Returns: object
set_block_paramsADestructiveIdempotent
Change parameters on the loaded rig without saving. Numbers are normalized 0-1.
With display, give numbers in the units the pedal shows, like -3 for -3.0 dB or 800 for
800 Hz, and options by name. Infinite reverb time is "Inf". describe_block has the ranges,
and a value outside them is refused. Returns the values read back, in the same units.
Inputs: block (required), values (required), display. Returns: object
set_footswitchADestructiveIdempotent
Make footswitch 1-6 control one module, without saving.
The switch becomes a Toggle, and name replaces its label. list_footswitch_actions has the
valid modules and operations; an operation the pedal doesn't offer is refused. "Unassigned"
clears the switch and ignores operation. MIDI Out can't be assigned here.
Inputs: module (required), switch (required), name, operation. Returns: object
set_mixADestructiveIdempotent
Set parallel path mixing without saving.
Keys: Para1Level, Para2Level, Para1Pan, Para2Pan, ParaDelay, ParaXFade. Values are
normalized 0-1: for pans 0 is left, 0.5 centre and 1 right; for level 0.75 is -6 dB.
With display, give dB, percent (-100 is left) and microseconds instead.
Inputs: values (required), display. Returns: object
set_routingADestructiveIdempotent
Change signal routing without saving. See list_routings for the slot layout.
Inputs: routing (required). Returns: object
set_sceneADestructiveIdempotent
Make footswitch 1-6 a scene, or edit one, without saving. Reads the result back.
blocks maps blocks in the chain to "on", "off" or "nochange", and replaces the scene's
whole map: blocks it doesn't list become "nochange". doubling and path are "A", "B" or
"nochange". presets maps blocks to a preset to recall, or "No Preset" to clear one.
color is 0-13. Anything you leave out keeps its current value.
state 2 edits the second state, which each press alternates with the first. It needs an
existing scene, and creates the second state if there isn't one.
name is shared by both states.
Check mismatches and warnings in the result.
Inputs: name (required), switch (required), path, color, +4 more. Returns: object
set_slot_blockADestructive
Put a block in chain slot 1-14 without saving. Its parameters reset shortly afterwards.
Refused for blocks the firmware lists but has no object for, such as ReValver Amp 2 and
C-Verb 2. Returns the chain and warnings, such as when Auto Assign Footswitches may
have put the block on a free switch.
Inputs: slot (required), block (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools target a distinct resource+action (rigs vs blocks vs scenes vs routings), and descriptions clarify boundaries well. The main risk is the footswitch cluster (get_footswitch_settings vs get_footswitches vs list_footswitch_actions vs set_footswitch) and block cluster (get_block vs describe_block vs list_blocks vs list_block_presets), where an agent must read carefully to pick correctly.
All 28 tools use snake_case with a leading verb (get_/list_/set_/find_/describe_/save_/load_/create_/activate_/remove_), and the verb choice matches read vs write semantics. No camelCase or mixed conventions appear.
28 tools is above the comfortable 3-15 band and there is some redundancy (two footswitch getters, get_current_rig vs list_rigs). The pedal domain is genuinely rich, so most tools earn their place, but the surface is heavy enough to be borderline.
Rig, block, scene, footswitch, routing and mix lifecycle are well covered with read and write operations plus a spec-driven create_rig. Gaps remain: setlists are read-only (no create/edit/reorder), and there are no delete operations for rigs or blocks.
Maintenance
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Connect AI assistants to explicitly paired computers, servers, and VMs for permitted remote actions.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to monitor and securely manage AsusWRT and AsusWRT-Merlin routers via SSH with allowlisted commands, supporting read-only monitoring and controlled mutations.473MIT
- AlicenseBqualityCmaintenanceEnables AI agents to manage Keenetic routers through the same RCI API used by the router's web interface, working directly over the local network without cloud involvement. It supports reading device statuses and executing configuration changes, with confirm, dry-run, and destructive-action safeguards.23PolyForm Noncommercial 1.0.0
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to inspect, query, and diagnose an Octopus instance and, when write access is enabled, create releases, deploy releases, run runbooks, and adjust feature toggles.547 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to automatically discover and control supported laboratory instruments over USB, LAN, and serial connections, including power-supply output, setpoint, and protection management plus multimeter measurements.4MIT