Skip to main content
Glama
headrush-mcp

headrush-mcp

by Haervwe

# 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

  • uv

  • An MCP client that supports stdio servers, such as Claude Code or Claude Desktop

Related MCP server: keenetic

Setup

  1. Get the code and install it:

    git clone https://github.com/Haervwe/headrush-mcp.git
    cd headrush-mcp
    uv sync
  2. Check the pedal is reachable. Open http://headrushflexprime.local in a browser, and you should see the Remote Editor. If not, use the IP shown on the pedal under Menu → Global Settings.

  3. 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"
          }
        }
      }
    }
  4. Restart your client and ask it something like "what rig is loaded on my HeadRush?"

Settings

Variable

Default

Purpose

HEADRUSH_HOST

headrushflexprime.local

The pedal's hostname or IP. An IP avoids mDNS lookups, but use a DHCP reservation so it doesn't change

HEADRUSH_ALLOW_WRITES

off

Set to 1 to enable tools that change the pedal

Tools

Read:

Tool

What it does

get_status

Firmware, loaded rig, unsaved-edit flag, DSP load

list_rigs, list_setlists, get_setlist

Browse your library

get_current_rig

Loaded rig's routing, mix and chain

get_footswitches

Footswitch summary

get_scene

One scene's blocks, A/B doubling, path, presets and color, including a second state if it has one

list_footswitch_actions

What a footswitch can control: modules and their operations

get_footswitch_settings

Global tuner, looper and auto-assign settings

get_rig_spec_format

The create_rig spec format, also available as a resource

find_models

Search blocks, models and installed files by name or by the gear they're inspired by (details)

list_blocks, list_block_presets

Available blocks and their presets

get_block, describe_block

A block's values, as 0-1 or as shown on the pedal, and its parameter schema

list_routings

Signal routings and their slot layouts

Write (needs HEADRUSH_ALLOW_WRITES=1):

Tool

What it does

Saved?

set_block_params, set_slot_block

Edit blocks, in 0-1 or real units, and the chain

No

set_routing, set_mix

Change routing and parallel mixing

No

set_footswitch, set_scene, remove_scene_second_state

Assign footswitches and scenes, including a scene's second state

No

activate_scene

Fire a scene

No

load_rig

Switch rigs

No

create_rig

Build, verify and save a rig from a spec

Yes, as a new rig

save_rig_as_new

Save under a new name

Yes, as a new rig

save_loaded_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_rig and create_rig are 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_new and create_rig are 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_rig is 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_block and create_rig refuse blocks that the pedal lists but has no object for, like ReValver Amp 2 on current firmware. Writing one of those crashed a Core's audio engine in a community test.

  • create_rig only 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_block and create_rig warn when that may take a switch, and get_footswitches reports the setting.

  • Numbers are normalized by default: parameters are 0-1 on the wire. Pass display=true to get_block, set_block_params or set_mix to use the units the pedal shows, like -3 for -3.0 dB, or display_params in a rig spec. See the API reference for the conversions.

  • Second instances: names ending in 2, like Amp 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:

  1. Go to Global Settings > General.

  2. Set Assign Tuner Footswitch (the hold function of switch 3) or Assign Looper Footswitch (the hold of switch 2) to Bank A/B.

  3. 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

stern-stereo-test.json

Mike Stern-inspired detune, delay and overdrive on two parallel amps, with scenes (notes)

stern-tipatinas.json

The same idea on one amp, using about half the DSP

metheny-follow-me.json

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 .local fails, set HEADRUSH_HOST to the IP. Check you're on the same network and not routing through a VPN. If New Connection Attempts is set to Deny under Global Settings > HeadRush Remote, the pedal rejects new clients (User Guide p.61), which probably looks like a network failure (untested)

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 HEADRUSH_ALLOW_WRITES to 1 and restart your client

"Has unsaved edits"

Save or discard them on the pedal first

"Unsaved edits made through this server"

Save them with save_loaded_rig or save_rig_as_new, or load another rig on the pedal to discard them

create_rig reports mismatches

Nothing was saved. Retry with resume_draft, or discard the draft on the pedal

resume_draft is refused

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 create_rig without it

"Didn't confirm saving"

The pedal didn't list the new name in time. Check list_rigs before trying again, since it may have saved

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 pytest

Tests 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_scene fires 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

MIT

Available Tools

28 tools
activate_sceneA
Destructive

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_blockB
Read-only

Read a block's parameter schema: types, display ranges and options.

Inputs: block (required). Returns: object

find_modelsA
Read-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_blockA
Read-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_rigA
Read-only

Get the loaded rig's name, routing, parallel mix and block chain.

Inputs: no named parameters. Returns: object

get_footswitchesA
Read-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_settingsA
Read-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_formatB
Read-only

Get the create_rig spec format, including footswitches, scenes and routings.

Inputs: no named parameters. Returns: result

get_sceneA
Read-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_setlistC
Read-only

Read one setlist.

Inputs: setlist_id (required).

get_statusA
Read-only

Get firmware, loaded rig, unsaved-edit flag and DSP load.

Inputs: no named parameters. Returns: object

list_block_presetsC
Read-only

List a block's factory and user presets.

Inputs: block (required). Returns: result

list_blocksA
Read-only

List block names usable in a chain slot. Names ending in ' 2' are second instances.

Inputs: no named parameters. Returns: result

list_footswitch_actionsA
Read-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_rigsA
Read-only

List every rig on the pedal with its id.

Inputs: no named parameters. Returns: result

list_routingsB
Read-only

List signal routings and which chain slots belong to each section.

Inputs: no named parameters. Returns: result

list_setlistsA
Read-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_stateB
DestructiveIdempotent

Go back to one state on the scene on footswitch 1-6, without saving.

Inputs: switch (required). Returns: object

save_loaded_rigA
DestructiveIdempotent

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_paramsA
DestructiveIdempotent

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_footswitchA
DestructiveIdempotent

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_mixA
DestructiveIdempotent

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_routingA
DestructiveIdempotent

Change signal routing without saving. See list_routings for the slot layout.

Inputs: routing (required). Returns: object

set_sceneA
DestructiveIdempotent

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_blockA
Destructive

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

    B3.4/5.0

    Scored across 28 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to monitor and securely manage AsusWRT and AsusWRT-Merlin routers via SSH with allowlisted commands, supporting read-only monitoring and controlled mutations.
      47
      3
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      23
      PolyForm Noncommercial 1.0.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      4
      MIT