<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png">
    <img src="assets/logo.png" width="260" alt="A pixel-art mascot sitting on a guitar amp, turning one of its knobs">
  </picture>
</p>

<h1 align="center">boss-katana-mcp</h1>

<p align="center">
  <em>Say the tone. The knobs turn themselves.</em>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/license-MIT-2b2622?style=flat-square&labelColor=111111" alt="MIT license">
  <img src="https://img.shields.io/badge/Claude%20Code-2b2622?style=flat-square&labelColor=111111&logo=claude&logoColor=d97757" alt="Claude Code supported">
  <img src="https://img.shields.io/badge/Codex%20CLI-2b2622?style=flat-square&amp;labelColor=111111&amp;logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyBmaWxsPSIjZmZmZmZmIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik04LjA4Ni40NTdhNi4xMDUgNi4xMDUgMCAwMTMuMDQ2LS40MTVjMS4zMzMuMTUzIDIuNTIxLjcyIDMuNTY0IDEuN2EuMTE3LjExNyAwIDAwLjEwNy4wMjljMS40MDgtLjM0NiAyLjc2Mi0uMjI0IDQuMDYxLjM2NmwuMDYzLjAzLjE1NC4wNzZjMS4zNTcuNzAzIDIuMzMgMS43NyAyLjkxOCAzLjE5OC4yNzguNjc5LjQxOCAxLjM4OC40MjEgMi4xMjZhNS42NTUgNS42NTUgMCAwMS0uMTggMS42MzEuMTY3LjE2NyAwIDAwLjA0LjE1NSA1Ljk4MiA1Ljk4MiAwIDAxMS41NzggMi44OTFjLjM4NSAxLjkwMS0uMDEgMy42MTUtMS4xODMgNS4xNGwtLjE4Mi4yMmE2LjA2MyA2LjA2MyAwIDAxLTIuOTM0IDEuODUxLjE2Mi4xNjIgMCAwMC0uMTA4LjEwMmMtLjI1NS43MzYtLjUxMSAxLjM2NC0uOTg3IDEuOTkyLTEuMTk5IDEuNTgyLTIuOTYyIDIuNDYyLTQuOTQ4IDIuNDUxLTEuNTgzLS4wMDgtMi45ODYtLjU4Ny00LjIxLTEuNzM2YS4xNDUuMTQ1IDAgMDAtLjE0LS4wMzJjLS41MTguMTY3LTEuMDQuMTkxLTEuNjA0LjE4NWE1LjkyNCA1LjkyNCAwIDAxLTIuNTk1LS42MjIgNi4wNTggNi4wNTggMCAwMS0yLjE0Ni0xLjc4MWMtLjIwMy0uMjY5LS40MDQtLjUyMi0uNTUxLS44MjFhNy43NCA3Ljc0IDAgMDEtLjQ5NS0xLjI4MyA2LjExIDYuMTEgMCAwMS0uMDE3LTMuMDY0LjE2Ni4xNjYgMCAwMC4wMDgtLjA3NC4xMTUuMTE1IDAgMDAtLjAzNy0uMDY0IDUuOTU4IDUuOTU4IDAgMDEtMS4zOC0yLjIwMiA1LjE5NiA1LjE5NiAwIDAxLS4zMzMtMS41ODkgNi45MTUgNi45MTUgMCAwMS4xODgtMi4xMzJjLjQ1LTEuNDg0IDEuMzA5LTIuNjQ4IDIuNTc3LTMuNDkzLjI4Mi0uMTg4LjU1LS4zMzQuODAyLS40MzguMjg2LS4xMi41NzMtLjIyLjg2MS0uMzA0YS4xMjkuMTI5IDAgMDAuMDg3LS4wODdBNi4wMTYgNi4wMTYgMCAwMTUuNjM1IDIuMzFDNi4zMTUgMS40NjQgNy4xMzIuODQ2IDguMDg2LjQ1N3ptLS44MDQgNy44NWEuODQ4Ljg0OCAwIDAwLTEuNDczLjg0MmwxLjY5NCAyLjk2NS0xLjY4OCAyLjg0OGEuODQ5Ljg0OSAwIDAwMS40Ni44NjRsMS45NC0zLjI3MmEuODQ5Ljg0OSAwIDAwLjAwNy0uODU0bC0xLjk0LTMuMzkzem01LjQ0NiA2LjI0YS44NDkuODQ5IDAgMDAwIDEuNjk1aDQuODQ4YS44NDkuODQ5IDAgMDAwLTEuNjk2aC00Ljg0OHoiPjwvcGF0aD48L3N2Zz4%3D" alt="Codex CLI supported">
  <img src="https://img.shields.io/badge/Gemini%20CLI-2b2622?style=flat-square&labelColor=111111&logo=googlegemini&logoColor=8E75B2" alt="Gemini CLI supported">
  <img src="https://img.shields.io/badge/MCP-stdio-2b2622?style=flat-square&labelColor=111111&logo=modelcontextprotocol&logoColor=white" alt="MCP stdio server">
  <img src="https://img.shields.io/badge/amp-KATANA%20Gen%203-2b2622?style=flat-square&labelColor=111111" alt="BOSS KATANA Gen 3">
  <img src="https://img.shields.io/badge/platform-Windows-2b2622?style=flat-square&labelColor=111111" alt="Windows">
  <img src="https://img.shields.io/badge/node-%E2%89%A524-2b2622?style=flat-square&labelColor=111111&logo=nodedotjs&logoColor=white" alt="Node.js 24 or newer">
  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-2b2622?style=flat-square&labelColor=111111" alt="PRs welcome"></a>
</p>

<p align="center">
  <img src="assets/hero.png" width="880" alt="boss-katana-mcp. Live in BOSS TONE STUDIO. Say the tone, the knobs turn themselves. 20 MCP tools, 13 sections, 3 agents, 0 clicks.">
</p>

Talk to your **BOSS KATANA Gen 3** from [Claude Code](https://claude.com/claude-code),
[Codex CLI](https://github.com/openai/codex) or [Gemini CLI](https://github.com/google-gemini/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"

<p align="center">
  <img src="assets/demo-thrash.gif" width="880" alt="Claude Code setting a thrash metal tone; the knobs in BOSS TONE STUDIO move live">
</p>

### "write blues tones with long sustain and delay"

<p align="center">
  <img src="assets/demo-blues.gif" width="880" alt="Claude Code setting a blues tone with sustain and delay; the effects in BOSS TONE STUDIO switch live">
</p>

<p align="center">
  <img src="assets/before-after.png" width="880" alt="One sentence, twelve changes. Prompt: write a thrash metal tone. Amp type LEAD to BROWN, gain 55 to 65, bass 55 to 65, middle 70 to 40, treble 60 to 65, presence 50 to 60, T-SCREAM drive 40 to 0, booster tone 0 to 10, booster level 70 to 80, delay on to off, reverb HALL to ROOM, noise gate threshold 30 to 45.">
</p>

<p align="center">
  <img src="assets/who-is-it-for.png" width="880" alt="Three players, one amp. Thinks in sounds, not settings: Hendrix clean, thick doom riff. Knows exactly what they want: gain 60, treble +2, delay 350 ms. Has a guitar in their hands: a bit brighter, delay off.">
</p>

## 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](docs/gen1-write-support.md) and the
[approved physical session report](docs/gen1-hardware-metal-2026-10-23.md).

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](docs/gen1-user-command-log.md).

See [architecture and source evidence](docs/gen1-architecture.md),
[compatibility and opt-ins](docs/gen1-compatibility.md), and
[test plan](docs/gen1-test-plan.md). The
[physical read-only report and raw evidence](docs/gen1-hardware-readonly-2026-10-23.md)
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**

```powershell
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](#security) first)

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

**3. Register the MCP server** as `katana`

```powershell
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
```

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

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

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

```text
> 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

<p align="center">
  <img src="assets/how-it-works.png" width="880" alt="How it works. Your agent (Claude Code, Codex CLI, Gemini CLI) talks MCP over stdio to the katana MCP server, which uses the DevTools Protocol on port 9222 to drive BOSS TONE STUDIO, which sends SysEx DT1 over USB MIDI to the KATANA Gen 3.">
</p>

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.

<p align="center">
  <a href="docs/design.md"><img src="https://img.shields.io/badge/read%20the-design%20notes%20%E2%86%92-2b2622?style=for-the-badge&labelColor=111111" alt="Read the design notes"></a>
</p>

<details>
<summary><b>MCP tools</b></summary>

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

</details>

<details>
<summary><b>Troubleshooting</b></summary>

| 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) |

</details>

<details>
<summary><b>Development</b></summary>

```powershell
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)
```

</details>

## 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](CONTRIBUTING.md) to get started.

## License

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

<sub>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.</sub>