headrush-mcp

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

Requirements

• A HeadRush Flex Prime on current firmware, on Wi-Fi

• A computer on the same network

• uv

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

Related MCP server: gnmi-mcp-server

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

Tools

Read:

Write (needs HEADRUSH_ALLOW_WRITES=1):

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.

• save_rig_as_new and create_rig are refused if the name already exists.

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

• create_rig only saves if every value reads back correctly.

Stay on a trusted network. The pedal's API is plain HTTP with no login, so anything on your network can 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 separate banks of three. Put what you use most on the same bank.

• Numbers are normalized: parameters are 0-1 on the wire, whatever range describe_block displays. See the API reference for converting values.

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

Example rigs

Starting points in rigs/, to adapt with your own ears:

To try one, ask your assistant to create_rig with the file's full path.

Troubleshooting

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.

• Only Toggle footswitches and single-state scenes are supported.

License

MIT