Skip to main content
Glama
Sign In
boss-katana-mcp

boss-katana-mcp

by dogakocak
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Talk to your BOSS KATANA Gen 3 from Claude Code, Codex CLI or Gemini CLI. Describe a tone and the knobs in BOSS TONE STUDIO move live, as if you had turned them yourself. Then save it to a channel on the amp, keep it in a liveset, share it as a .tsl file, or ask what your footswitches and pedals are set to do.

Demo

"write a thrash metal tone"

"write blues tones with long sustain and delay"

Related MCP server: nux-mg30-mcp

Install

Experimental Gen 1 support

KATANA-50 Gen 1 has an isolated, experimental direct MIDI backend. Its read-only adapter path was verified on one operator-labelled KATANA-50 Gen 1 on 2026-10-23: identity matched, all 20 addresses read successfully in 23 transactions, start/end sentinels matched and ports closed cleanly. Firmware remains unknown; this is not a compatibility claim for other devices/firmware. Default startup and the existing Gen 3 tools are unchanged. Set KATANA_BACKEND=gen1 to expose katana_gen1_* tools; hardware access is off by default, including discovery. Status and parameter listing work without a device. The optional native dependency is installed by npm install.

The original 20 reads are retained; 11 additional source-backed effective controls were read during a later explicitly approved metal-tone application on the same device. That session passed identity, 70 RQ1, nine temporary DT1 writes with readback, and clean disconnect. It did not save a patch or alter firmware. Audible quality, other firmware and physical fault recovery remain unverified.

katana_gen1_apply_tone {"name":"metal"} previews with zero I/O by default. Applying requires dryRun:false, a connection and both write/low-MASTER startup opt-ins. Bounded effective amp/Gain/EQ/effect-toggle/NS1 controls are also available through katana_gen1_set. Temporary LEVEL is capped at 10; the metal recipe ends at min(previous LEVEL,5). Keep physical MASTER low. All panel/system, patch-save and firmware writes remain blocked; Gen 3 tone recipes do not apply to Gen 1. See write support and its source evidence and the approved physical session report.

The later operator-commanded delay/reverb extension adds DelayLevel and bounded ReverbLevel writes (0..50): 32 readable keys, 16 writable effective controls. Both effects ON and wet levels 15 passed readback on the recorded device; audible quality remains unverified. Details are in the command journal.

See architecture and source evidence, compatibility and opt-ins, and test plan. The physical read-only report and raw evidence include all values, checksums and an offline evidence verifier.

Gen 3 setup

You need: Windows 10/11 · a KATANA Gen 3 on USB · BOSS TONE STUDIO for KATANA Gen 3 (tested 1.1.0) · Node.js 24+ · Claude Code, Codex CLI or Gemini CLI.

1. Build

git clone https://github.com/dogakocak/boss-katana-mcp.git
cd boss-katana-mcp
npm install
npm run build

2. Open BOSS TONE STUDIO's debug port (current user, no admin; read Security first)

powershell -ExecutionPolicy Bypass -File scripts\Enable-BossKatanaMcp.ps1

3. Register the MCP server as katana

claude mcp add katana -- node C:/path/to/boss-katana-mcp/dist/index.js   # Claude Code
codex mcp add katana -- node C:/path/to/boss-katana-mcp/dist/index.js    # Codex CLI
gemini mcp add katana node C:/path/to/boss-katana-mcp/dist/index.js      # Gemini CLI

Codex asks before every tool call; add default_tools_approval_mode = "approve" under [mcp_servers.katana] in config.toml to skip that.

4. Link the skill (a junction stays in sync with the repo)

# Claude Code
New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\skills\katana-tone" -Target "C:\path\to\boss-katana-mcp\skill\katana-tone"
# Codex CLI and Gemini CLI share .agents\skills
New-Item -ItemType Junction -Path "$env:USERPROFILE\.agents\skills\katana-tone" -Target "C:\path\to\boss-katana-mcp\skill\katana-tone"

Restart your CLI, switch on the amp and ask for a tone. The agent opens BOSS TONE STUDIO and connects the amp itself.

> give me an 80s hard rock lead tone
> a bit less gain, more middle
> volume 12
> save it to B2 as "80S LEAD"
> add it to a liveset called Gig and export that as a .tsl file
> what do my GA-FC footswitches do?
NOTE

katana_set edits the current patch live. Save it with katana_write (or WRITE in BOSS TONE STUDIO / on the amp), or keep it in a liveset.

How it works

The MCP server attaches to BOSS TONE STUDIO's WebView2 page and calls the app's own code, so the app stays the only program talking to the amp. The katana-tone skill tells the agent how to turn a description into those changes.

Tool

What it does

katana_status

App reachable? amp connected? patch name, active variation of each effect

katana_launch

Starts BOSS TONE STUDIO with the debug port and connects the amp

katana_connect

Reconnects an open BOSS TONE STUDIO to the amp

katana_get

Reads the tone as friendly keys (amp.gain, booster.type, …)

katana_set

Sets one or more parameters at once

katana_list_params

Lists a section's keys, ranges and option names

katana_controls

Shows what the footswitches and expression pedals (amp jacks, GA-FC, GA-FC EX) are assigned to

katana_list_patches

Lists the amp's stored patches (PANEL, A1..B4) and the selected slot

katana_select_patch

Switches the amp to a stored slot (replaces the current tone)

katana_write

Saves the current tone to a slot under a name (refuses to replace a stored patch unless overwrite)

katana_liveset_list / _create / _rename / _delete

Manage BOSS TONE STUDIO livesets

katana_liveset_add_current

Stores the current tone in a liveset

katana_liveset_load

Loads a liveset patch into the edit buffer (replaces the current tone)

katana_liveset_to_amp / _from_amp

Copies patches between a liveset and the amp's slots

katana_liveset_export / _import

Saves / loads a liveset as a .tsl file

Symptom

Fix

BOSS TONE STUDIO is not reachable

Run Enable-BossKatanaMcp.ps1, then restart BOSS TONE STUDIO

ampConnected: false

Check power and USB, then ask the agent to reconnect (right after switching the amp on, the first try can time out while BOSS TONE STUDIO connects by itself; a second try works)

… holds "…". Ask the user, then call again with overwrite: true.

Saving would replace a stored patch, liveset patch or file; the agent asks you before it overwrites

Values look like defaults (amp.volume 50, patch KATANA)

The patch hasn't loaded yet; wait for ampConnected: true

running without the debug port

Close BOSS TONE STUDIO and let the agent start it

Port 9222 already in use

Close the other tool using it (e.g. a browser with remote debugging)

npm test           # unit tests (needs BOSS TONE STUDIO installed and started once)
npm run test:e2e   # against a running BOSS TONE STUDIO with the amp connected
python assets/src/build.py   # rebuild the README images (Pillow + Edge)

Security

WARNING

Enable-BossKatanaMcp.ps1 makes BOSS TONE STUDIO always open a DevTools port on 127.0.0.1:9222. While the app is open, any local process can control it through that port. Run scripts\Disable-BossKatanaMcp.ps1 when you don't need it.

Contributing

Issues and pull requests are welcome: tests on other KATANA Gen 3 models, better tone recipes for the skill, new skill evals, setup notes for other agents. See CONTRIBUTING.md to get started.

License

MIT © 2026 Doğa Koçak. A hobby project, made for fun and without any commercial intent.

Not affiliated with or endorsed by Roland / BOSS or Anthropic. "BOSS", "KATANA" and "BOSS TONE STUDIO" are trademarks of Roland Corporation; the mascot in the logo is Anthropic's Claude Code character. No Roland files are included in this repository.

Available Tools

6 tools
katana_connectA

Connect an already open BOSS TONE STUDIO to the KATANA (e.g. after the amp was switched off and on) and wait until the amp patch is loaded.

Inputs: no named parameters.

katana_getA

Read the current tone from BOSS TONE STUDIO as friendly keys (amp.volume, booster.type, ...). Effects show the active variation.

Inputs: sections.

katana_launchA

Open BOSS TONE STUDIO with the debug port if it is not open yet, connect it to the KATANA (answers the "Connect with" dialog) and wait until the amp patch is loaded.

Inputs: no named parameters.

katana_list_paramsB

List the keys of one section with their ranges and option names (for MOD/FX this includes every effect type's detail parameters).

Inputs: section (required).

katana_setA

Set one or more parameters live (edit buffer, not saved to a patch). The BOSS TONE STUDIO UI updates immediately. Keys like amp.volume, amp.type ("LEAD"), booster.on (true/false), delay.time; use katana_list_params for ranges. All-or-nothing validation, no clamping.

Inputs: changes (required).

katana_statusA

Check that BOSS TONE STUDIO is reachable, whether a KATANA Gen 3 is connected, the current patch name and which variation (green/red/yellow) each effect shows.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but katana_launch and katana_connect overlap because launch can also connect, and katana_status slightly overlaps with katana_get around current patch/effect variation information. The descriptions mostly clarify when to use each, so an agent can usually choose correctly.

    Naming Consistency5/5

    All tools use a consistent katana_ prefix followed by a short action-oriented name, such as katana_get, katana_set, and katana_list_params. The convention is predictable and readable throughout.

    Tool Count5/5

    Six tools is well-scoped for a focused amp-control server: connection lifecycle, parameter discovery, read, write, and status. Each tool has a clear role, and there are no redundant extras.

    Completeness3/5

    The live-control workflow is covered from launch/connect through parameter discovery, read, and write, but katana_set explicitly edits only the live buffer and there is no tool to save the current tone to a patch. Patch switching or listing is also absent, which creates a notable dead end for persistence-oriented workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • nux-mg30-mcp

      voronkovd
      A
      license
      Not graded
      quality
      B
      maintenance
      Lets AI assistants control a NUX MG-30 guitar processor over USB MIDI by picking amp, cab, drive, modulation, delay and reverb models, toggling blocks, and setting knobs by name. It can also read, save, rename, back up and restore presets on the device, and apply whole tone recipes from JSON patch files.
      31 PyPI
      MIT

    • Pocket Master MCP

      voronkovd
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables an AI assistant to control a Sonicake Pocket Master guitar processor over USB MIDI by describing tones in plain words — selecting amp/cab/effect models, setting parameters, reordering the signal chain, and saving, renaming, backing up or restoring presets. It also provides offline tools for inspecting firmware and rebuilding it with a translated UI, such as Russian.
      29 PyPI
      1
      MIT