Skip to content
Back to search

mefcs-mcp

MCP server to control the M-VAVE Tank-G guitar pedal (presets, NAM amp captures, cab IRs) and search/install TONE3000 tones

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cayocan--mefcs-mcp/badge.svg)](/listings/cayocan--mefcs-mcp)

HTML

<a href="/listings/cayocan--mefcs-mcp"><img src="/api/listings/cayocan--mefcs-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. Get the code
git clone https://github.com/cayocan/mefcs-mcp.git
cd mefcs-mcp

# 2. Install dependencies and build
npm install
npm run build

# 3. Optional: run the tests (they compare the output with captured M-EFCS traffic)
npm test

The server entry point is `dist/src/server.js`. Once the package is published on npm you can skip the clone and use `npx -y mefcs-mcp` instead (see [Publishing](#publishing)).

Find the full path of `mefcs_ks_bridge.exe` inside your M-EFCS folder (for example `C:\Program Files\M-EFCS\mefcs_ks_bridge.exe`). Standard locations are detected automatically; otherwise set `MEFCS_BRIDGE_PATH`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 315 lines
  1. <p align="right"><b>English</b> | <a href="README.pt-BR.md">Português (BR)</a></p>
  2. # mefcs-mcp
  3. An [MCP](https://modelcontextprotocol.io) server that lets AI assistants (Claude, Cursor, VS Code Copilot, Gemini CLI, Codex and any other MCP client) control an **M-VAVE Tank-G** guitar pedal and pull tones from **TONE3000**.
  4. It talks to the pedal over USB with the same protocol as the official **M-EFCS** app. The protocol is reverse engineered and documented in [docs/PROTOCOL.md](docs/PROTOCOL.md). It uses the USB helper that ships with M-EFCS, so nothing has to be installed on the pedal.
  5. > Unofficial project, not affiliated with M-VAVE / Sinco or TONE3000. Firmware update, repair and factory-restore functions are intentionally **not** implemented.
  6. ---
  7. ## Contents
  8. 1. [What it can do](#what-it-can-do)
  9. 2. [Requirements](#requirements)
  10. 3. [Installation](#installation)
  11. 4. [Connecting it to an AI client](#connecting-it-to-an-ai-client)
  12. 5. [Configuration](#configuration)
  13. 6. [TONE3000 setup](#tone3000-setup)
  14. 7. [Tool reference](#tool-reference)
  15. 8. [Example prompts](#example-prompts)
  16. 9. [Safety](#safety)
  17. 10. [How it works](#how-it-works)
  18. 11. [Troubleshooting](#troubleshooting)
  19. 12. [Development](#development)
  20. 13. [Publishing](#publishing)
  21. 14. [License](#license)
  22. ---
  23. ## What it can do
  24. **Pedal (Tank-G)**
  25. - Read all 36 presets, or the live values of the active preset.
  26. - Switch presets, toggle bypass.
  27. - Edit any value (amp slot, gain, EQ, volume, gate, MOD / DELAY / REVERB type and knobs, cab slot, LED color) and save it to the pedal. A backup is taken automatically first.
  28. - Tweak the active preset live without saving.
  29. - Export and import `.atkg` preset files, the same format as M-EFCS "Share/Import all presets". Imports are backed up and verified.
  30. - Upload an amp capture (NAM **A2** `.nam`, converted to "A2 Lite (Original)" like M-EFCS does) to amp slot 1-9, or preview it.
  31. - Upload a cab impulse response (`.wav`, any rate/bit depth, resampled to 44.1 kHz) to cab slot 1-8, or preview it.
  32. **TONE3000**
  33. - Search tones (NAM A2 captures by default, or IRs) by text, gear type, make/model, tags or creator.
  34. - See a tone's details and its downloadable models.
  35. - Download `.nam` / `.wav` files.
  36. - Install a TONE3000 model straight onto a pedal slot in one step.
  37. - When keys or a login are missing, the server **opens the right TONE3000 page in your browser** for you.
  38. ## Requirements
  39. | | |
  40. |---|---|
  41. | OS | Windows 10/11. The USB helper is a Windows program. |
  42. | Node.js | 20 or newer (`node -v`) |
  43. | M-EFCS | Installed. The server uses its `mefcs_ks_bridge.exe`. |
  44. | Pedal | M-VAVE Tank-G (v2) connected by USB |
  45. | TONE3000 | Free account, only for the TONE3000 tools |
  46. **Important:** only one program can talk to the pedal at a time. **Close M-EFCS** before the AI uses a pedal tool. Ask the AI to run `tankg_disconnect` before opening M-EFCS again.
  47. ## Installation
  48. ```powershell
  49. # 1. Get the code
  50. git clone https://github.com/cayocan/mefcs-mcp.git
  51. cd mefcs-mcp
  52. # 2. Install dependencies and build
  53. npm install
  54. npm run build
  55. # 3. Optional: run the tests (they compare the output with captured M-EFCS traffic)
  56. npm test
  57. ```
  58. The server entry point is `dist/src/server.js`. Once the package is published on npm you can skip the clone and use `npx -y mefcs-mcp` instead (see [Publishing](#publishing)).
  59. Find the full path of `mefcs_ks_bridge.exe` inside your M-EFCS folder (for example `C:\Program Files\M-EFCS\mefcs_ks_bridge.exe`). Standard locations are detected automatically; otherwise set `MEFCS_BRIDGE_PATH`.
  60. ## Connecting it to an AI client
  61. MCP is an open standard, so the same server works in every client that supports local (stdio) MCP servers. In each example, replace the paths with yours.
  62. ### Claude Desktop
  63. Edit `%APPDATA%\Claude\claude_desktop_config.json` and restart Claude Desktop:
  64. ```json
  65. {
  66. "mcpServers": {
  67. "mefcs": {
  68. "command": "node",
  69. "args": ["C:\\path\\to\\mefcs-mcp\\dist\\src\\server.js"],
  70. "env": {
  71. "MEFCS_BRIDGE_PATH": "C:\\Program Files\\M-EFCS\\mefcs_ks_bridge.exe",
  72. "MEFCS_BACKUP_DIR": "C:\\path\\to\\mefcs-mcp\\backups",
  73. "TONE3000_DOWNLOAD_DIR": "C:\\path\\to\\mefcs-mcp\\downloads"
  74. }
  75. }
  76. }
  77. }
  78. ```
  79. ### Claude Code
  80. ```powershell
  81. claude mcp add mefcs --scope user `
  82. -e MEFCS_BRIDGE_PATH="C:\Program Files\M-EFCS\mefcs_ks_bridge.exe" `
  83. -- node "C:\path\to\mefcs-mcp\dist\src\server.js"
  84. ```
  85. ### Cursor
  86. `%USERPROFILE%\.cursor\mcp.json` (global) or `.cursor/mcp.json` (project) takes the same `mcpServers` block as Claude Desktop.
  87. ### VS Code (GitHub Copilot agent mode)
  88. `.vscode/mcp.json`:
  89. ```json
  90. {
  91. "servers": {
  92. "mefcs": {
  93. "type": "stdio",
  94. "command": "node",
  95. "args": ["C:\\path\\to\\mefcs-mcp\\dist\\src\\server.js"],
  96. "env": { "MEFCS_BRIDGE_PATH": "C:\\Program Files\\M-EFCS\\mefcs_ks_bridge.exe" }
  97. }
  98. }
  99. }
  100. ```
  101. ### Windsurf, Cline, Gemini CLI and others
  102. They all accept the same three things: `command` = `node`, `args` = path to `dist/src/server.js`, and `env` = the variables below. The `mcpServers` JSON block from Claude Desktop goes in:
  103. - `~/.codeium/windsurf/mcp_config.json` (Windsurf)
  104. - Cline's MCP settings
  105. - `~/.gemini/settings.json` (Gemini CLI)
  106. ### OpenAI Codex CLI
  107. `%USERPROFILE%\.codex\config.toml`:
  108. ```toml
  109. [mcp_servers.mefcs]
  110. command = "node"
  111. args = ["C:\\path\\to\\mefcs-mcp\\dist\\src\\server.js"]
  112. env = { MEFCS_BRIDGE_PATH = "C:\\Program Files\\M-EFCS\\mefcs_ks_bridge.exe" }
  113. ```
  114. > Clients that only accept **remote** (HTTPS) MCP servers, such as web chat apps, cannot reach a USB pedal directly. The server has to run on the PC that has the pedal. See [Publishing](#publishing).
  115. ## Configuration
  116. | Variable | Default | Meaning |
  117. |---|---|---|
  118. | `MEFCS_BRIDGE_PATH` | auto-detected in Program Files / LocalAppData | Full path to `mefcs_ks_bridge.exe` |
  119. | `MEFCS_BACKUP_DIR` | `~/mefcs-mcp-backups` | Automatic preset backups (`TankG_<date>_<reason>.atkg`) |
  120. | `TONE3000_DOWNLOAD_DIR` | `~/mefcs-mcp-downloads` | Downloaded `.nam` / `.wav` files |
  121. | `TONE3000_CLIENT_ID` | (none) | TONE3000 publishable key; can also be saved at runtime |
  122. | `TONE3000_API_KEY` | (none) | TONE3000 secret key `t3k_cs_…`, alternative to the login |
  123. | `TONE3000_TOKEN_FILE` | `~/.mefcs-mcp/tone3000-tokens.json` | Saved TONE3000 session |
  124. | `MEFCS_CONFIG_FILE` | `~/.mefcs-mcp/config.json` | Keys saved with `tone3000_set_credentials` |
  125. | `MEFCS_NO_BROWSER` | (unset) | Set to `1` to never open the browser |
  126. ## TONE3000 setup
  127. You only do this once, and you never need to edit config files for it:
  128. 1. Ask the AI to search TONE3000 (for example "search TONE3000 for a Fender Twin"). Without keys, the server **opens https://www.tone3000.com/settings in your browser**.
  129. 2. Log in there and generate API keys. Give the **publishable key** (client id) to the AI, which saves it with `tone3000_set_credentials`. It is stored in `~/.mefcs-mcp/config.json` on your PC.
  130. 3. The server then **opens the TONE3000 approval page** with your code. Click approve, and the AI runs `tone3000_login_finish`.
  131. 4. Done. The session is saved and refreshed automatically. From now on, searches and downloads just work.
  132. Prefer not to log in? Put the secret key (`t3k_cs_…`) in `TONE3000_API_KEY` yourself instead. Don't paste secret keys into a chat.
  133. Notes:
  134. - The default rate limit is 100 requests per minute.
  135. - Searches default to NAM **A2** captures, because the Tank-G loads the *lite* part of A2 files. Standard (A1) WaveNet captures cannot be converted.
  136. - TONE3000's API terms ask independent developers to credit TONE3000.
  137. ## Tool reference
  138. ### Pedal
  139. | Tool | Inputs | What it does |
  140. |---|---|---|
  141. | `tankg_connect` | — | Opens the USB session (M-EFCS must be closed). Other tools connect on demand. |
  142. | `tankg_disconnect` | — | Releases the pedal so M-EFCS can be used. |
  143. | `tankg_status` | — | Active preset (`1A`…`9D`) and bypass state. |
  144. | `tankg_list_presets` | — | All 36 stored presets, decoded. |
  145. | `tankg_get_preset` | `preset?`, `live?` | One stored preset, or the live values of the active one. |
  146. | `tankg_select_preset` | `preset` | Switch preset. |
  147. | `tankg_update_preset` | `preset`, `changes`, `save?` (default true) | Edit and save. Backs up first. Also applied live if the preset is active. |
  148. | `tankg_set_live_values` | `changes` | Change the active preset without saving. |
  149. | `tankg_set_bypass` | `on` | Global bypass. |
  150. | `tankg_export_presets` | `path` | Save all presets to an `.atkg` file. |
  151. | `tankg_import_presets` | `path` | Replace all presets with an `.atkg` file (backup + read-back verification). |
  152. | `tankg_upload_amp_capture` | `namPath`, `slot?` 1-9, `name?` | Convert a NAM A2 capture and store it in an amp slot. Without `slot` it is only previewed. |
  153. | `tankg_upload_cab_ir` | `wavPath`, `slot?` 1-8, `level?` 0-100 | Store a WAV IR in a cab slot (max ~30 ms at 44.1 kHz). Without `slot` it is only previewed. |
  154. | `tankg_read_preset_file` | `path` | Decode an `.atkg` file offline. |
  155. | `tankg_effect_types` | — | Effect type indexes. |
  156. `changes` fields (all optional):
  157. | Field | Range |
  158. |---|---|
  159. | `ampOn` | bool |
  160. | `ampSlot` | 1-9 |
  161. | `gain`, `treble`, `middle`, `bass`, `volume` | 0-100 |
  162. | `gate` | 0-100, 0 = off |
  163. | `mod`, `delay`, `reverb` | `{ on, type 0-2, amount, param2 0-100 }` |
  164. | `cabSlot` | 0-8, 0 = off |
  165. | `color` | `{ r, g, b }` |
  166. Effect types follow the knob zones in the official manual:
  167. | Block | type 0 | type 1 | type 2 | amount | param2 |
  168. |---|---|---|---|---|---|
  169. | MOD | chorus | phaser | tremolo | mix | rate |
  170. | DELAY | analog | tape | dual | mix | time |
  171. | REVERB | room | spring | cloud | decay | mix |
  172. `amount` ranges from 0 to 42 (0 to 40 for type 2).
  173. ### TONE3000
  174. | Tool | Inputs | What it does |
  175. |---|---|---|
  176. | `tone3000_auth_status` | — | Shows the auth mode and whether you are logged in. |
  177. | `tone3000_set_credentials` | `clientId?`, `apiKey?` | Saves keys locally and starts the login (opens the approval page). |
  178. | `tone3000_login_start` / `tone3000_login_finish` | — | Device login. Start opens the browser; finish waits up to 60 s for approval. |
  179. | `tone3000_search` | `query?`, `gears?`, `makes?`, `tags?`, `creators?`, `sizes?`, `format?` (`nam`/`ir`), `sort?`, `calibrated?`, `page?`, `pageSize?` | Search tones. |
  180. | `tone3000_get_tone` | `toneId` | Details and downloadable models. |
  181. | `tone3000_download_model` | `modelId`, `dir?` | Download a `.nam` / `.wav`. |
  182. | `tankg_install_tone3000_model` | `modelId`, `slot?`, `name?`, `cabLevel?` | Download and send to an amp slot (`.nam`) or cab slot (`.wav`). |
  183. ## Example prompts
  184. - "Which preset is active on my Tank-G, and what does it have?"
  185. - "Turn off the reverb on 5D and lower the gain to 60."
  186. - "Make 1A's chorus subtler without saving, I want to hear it first."
  187. - "Back up all my presets to D:\\Backups\\tankg.atkg."
  188. - "Search TONE3000 for a Vox AC30 capture with lots of downloads and preview the best one."
  189. - "Install the Marshall JCM800 capture you found on amp slot 4 and point preset 3C at it."
  190. - "Find a Celestion V30 4x12 IR on TONE3000 and put it on cab slot 5."
  191. ## Safety
  192. - There is no code path to firmware update, repair or factory restore, and every write is checked against an address allow-list (see `assertAllowedWrite`).
  193. - Preset edits and imports back up all 36 presets first. Imports are verified by reading the bank back.
  194. - Values are validated: knobs 0-100 (the range M-EFCS uses), slots 1-9 / 1-8, effect amounts within the type's zone. Untouched legacy values are kept as they are.
  195. - Slot uploads overwrite the slot. Without `slot` they only preview, and nothing is stored.
  196. - The browser is only opened for `https://www.tone3000.com` pages.
  197. - TONE3000 keys and tokens stay on your PC (`~/.mefcs-mcp`).
  198. ## How it works
  199. ```
  200. AI client ──MCP (stdio)──> mefcs-mcp ──stdin/stdout──> mefcs_ks_bridge.exe ──USB MIDI (SysEx)──> Tank-G
  201. └──HTTPS──> TONE3000 API
  202. ```
  203. - `src/protocol/bridge.ts`: spawns the M-EFCS helper (`open-raw`) and speaks its text protocol (`send <hex>` → `data <hex>`).
  204. - `src/protocol/framing.ts`: SysEx frames: 8-bit frame → 7-bit LSB-first bitstream, inverted-sum checksum.
  205. - `src/devices/tankg.ts`: memory map (preset bank, live preset, select/bypass/commit, model buffers, slot store) plus the write allow-list.
  206. - `src/devices/tankg-presets.ts`: 21-byte preset record codec (`.atkg` layout).
  207. - `src/codecs/a2lite.ts`: NAM A2 → device amp buffer. It takes the lite submodel, transposes the convolution weights and precomputes the zero-input state.
  208. - `src/codecs/ir.ts`: WAV → device cab buffer (44.1 kHz, int24, max 1358 samples).
  209. - `src/tone3000/client.ts`: TONE3000 API v1 (device login, search, models, download).
  210. ## Troubleshooting
  211. | Problem | Fix |
  212. |---|---|
  213. | "M-EFCS is open" | Close M-EFCS; only one program can use the pedal. |
  214. | "mefcs_ks_bridge.exe not found" | Set `MEFCS_BRIDGE_PATH` to the file inside your M-EFCS folder. |
  215. | "No M-VAVE device found" | Check the USB cable/port; make sure the pedal is on. |
  216. | "Timed out waiting for the pedal" | Unplug and replug the pedal, then retry. Make sure nothing else is using it. |
  217. | M-EFCS can't find the pedal after using the AI | Ask the AI to run `tankg_disconnect`, or restart the AI client. |
  218. | "not an A2 (SlimmableContainer) capture" | Pick an A2 capture on TONE3000 (search already filters for them). |
  219. | TONE3000 rate limit | Wait a minute (100 requests/min). |
  220. | A preset change sounds wrong | Restore the latest backup in `MEFCS_BACKUP_DIR` with `tankg_import_presets`. |
  221. ## Development
  222. ```powershell
  223. npm run build # TypeScript -> dist/
  224. npm test # golden tests against captured M-EFCS traffic + TONE3000 client tests
  225. node scripts/smoke-test.mjs out.atkg # live read-only test on a real pedal (M-EFCS closed)
  226. node scripts/normalize-knobs.mjs --dry-run
  227. ```
  228. Two golden tests compare against third-party TONE3000 captures that are not redistributed in this repo. They are skipped automatically when `test/fixtures/mesa.nam` / `ir8.wav` are absent.
  229. To add another M-VAVE device (MK300, Tank-B, …), add a driver under `src/devices/` with that device's memory map and model format. The framing and the bridge are shared. Capture its traffic first (see `docs/PROTOCOL.md`).
  230. ## Publishing
  231. The goal is that anyone can run it with `npx -y mefcs-mcp` and find it in MCP directories.
  232. 1. **GitHub:** push this repository (for example `github.com/cayocan/mefcs-mcp`) and add a license.
  233. 2. **npm:** `npm login`, then `npm publish`. `prepublishOnly` builds and tests first. After this, clients can use:
  234. ```json
  235. { "command": "npx", "args": ["-y", "mefcs-mcp"], "env": { "MEFCS_BRIDGE_PATH": "..." } }
  236. ```
  237. 3. **Official MCP Registry:** `package.json` already has `"mcpName": "io.github.cayocan/mefcs-mcp"` and the repository has a `server.json`. Install `mcp-publisher`, then run `mcp-publisher login github` and `mcp-publisher publish`. Keep the versions in `package.json` and `server.json` equal.
  238. 4. **Directories (optional):** Smithery, Glama, mcp.so, and the Cursor / VS Code MCP galleries can list it from the npm package or the registry.
  239. Because the pedal is a local USB device, this is a **local (stdio)** server. Remote-only clients would need an HTTP transport running on the PC with the pedal, exposed through a secure tunnel. That is not included yet.
  240. ## License
  241. [MIT](LICENSE) © Cayo Aguiar. M-VAVE, Tank-G, M-EFCS and TONE3000 are trademarks of their respective owners.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.