Guitar Tone Assistant

Guitar Tone Assistant is a local Model Context Protocol (MCP) server that helps a compatible AI assistant design and deliver practical guitar tones using the TONE3000 plugin, Neural Amp Modeler (NAM), cabinet impulse responses, and AmpliTube 5 MAX.

The MCP server is the tone-design brain. It interprets the player's goal and rig, chooses the most useful workflow, and can return either a ready-to-load TONE3000 plugin preset, AmpliTube build instructions, or an adjustable AmpliTube amp paired with a TONE3000 cabinet IR. It does not process guitar audio itself.

What it can and cannot do

Guitar Tone Assistant can:

• Search live TONE3000 tone packs and cabinet IRs when an API credential is configured.

• Explain whether a capture includes an amp, an amp and cabinet, or only a cabinet IR.

• Decide between TONE3000-plugin, AmpliTube-only, and hybrid delivery based on the player's software and priorities.

• Compile exact selected TONE3000 tone/model IDs into a verified native .t3kpreset file.

• Return a local file path over stdio or a localhost download link over the HTTP transport.

• Search the complete, versioned 435-model AmpliTube 5 MAX v2 inventory, with richer tone-design metadata for the core recommendation set.

• Suggest starting settings and adjust them for guitar, pickup type, and tuning.

• Troubleshoot fizz, mud, harshness, boom, thinness, excessive compression, and weak pick attack.

• Compare two to four TONE3000 captures.

• Store an optional local description of the user's rig.

It does not:

• Listen to, analyze, transform, or play guitar audio.

• Load, install, or execute the generated preset or model files for the user.

• Control a DAW or AmpliTube.

• Create AmpliTube preset files.

• Reproduce a recorded artist tone exactly.

• Automatically apply a saved user profile to every recommendation.

Artist and album references are treated as useful starting points, not claims about exact studio equipment or settings.

Related MCP server: Ableton Copilot

Who this is for

The current MVP is aimed at guitarists who already use, or want to experiment with:

• TONE3000 for NAM captures and impulse responses.

• The official TONE3000 plugin for ready-to-load multi-block presets, or another NAM-compatible player for manual chains.

• AmpliTube 5 MAX for adjustable amp, cabinet, microphone, and effects chains.

• A DAW or plugin host capable of arranging multiple plugins.

• ChatGPT desktop, Codex CLI, the Codex IDE extension, or another MCP client.

Developers can also use the project as a starting point for a more complete guitar-tone MCP server.

The routing concepts that matter

Applying a cabinet to an amp-cab capture usually creates a muffled or phase-heavy double-cab sound. The server calls out this risk when the TONE3000 metadata is clear enough.

NAM captures are fixed snapshots. Turning a post-EQ control is not the same as changing the captured amplifier's original gain, tone stack, or master volume.

How to use the three workflows

TONE3000-focused

The assistant selects exact TONE3000 tone/model IDs and can ask the bundled compiler adapter to produce a native .t3kpreset file. The user then loads that file in the TONE3000 plugin. A typical internal chain is:

Guitar -> Audio interface -> TONE3000 plugin
  [Gate/boost as captured or hosted] -> Amp capture -> Cab/IR when required -> Tone EQ

If the selected capture is amp-cab, the assistant skips a separate cabinet by default to avoid double-cab coloration. Preset compilation requires exact TONE3000 IDs; recommendations remain separate from compilation so the assistant can explain the choice before creating a file.

AmpliTube-only

Typical chain inside AmpliTube:

Guitar -> Gate/boost -> AmpliTube amp -> AmpliTube cabinet and microphones -> Rack effects

This workflow offers continuously adjustable amp controls and does not require a NAM player.

Hybrid

The default hybrid keeps AmpliTube's amp controls adjustable while using a TONE3000 cabinet IR in AmpliTube's IR Loader:

Guitar -> AmpliTube gate/boost -> AmpliTube amp
-> AmpliTube IR Loader with a TONE3000 .wav cabinet IR
-> AmpliTube post-EQ, delay, and reverb

Disable AmpliTube's normal cabinet block while the external IR is active. A NAM amp capture is not an impulse response and cannot be loaded into the IR Loader. More advanced multi-plugin NAM/AmpliTube routing is still possible, but it is no longer what hybrid means by default.

Example requests

• “Find a tight 5150-style TONE3000 amp capture and pair it with a cabinet IR.”

• “Give me a TONE3000-only, AmpliTube-only, and hybrid version of this tone.”

• “Choose the best TONE3000 captures, then create a mono preset I can load in the plugin.”

• “I use a Les Paul with humbuckers in Drop C. Give me a modern metal starting point.”

• “This amp-and-cab capture sounds fizzy through my current chain. What should I change first?”

• “Compare these three TONE3000 links and tell me which one is most flexible.”

• “Give me a clean American combo-style tone.”

The returned knob values are starting points on a 0–10 scale. They are not guaranteed to match the labels or ranges of every physical or AmpliTube model.

Included MCP tools

Every tool has Zod input/output schemas and MCP annotations. The schemas describe the tool contract; the current TONE3000 client does not yet perform full runtime validation of every upstream response.

Requirements

• Node.js 20 or newer.

• npm.

• Git with submodule support.

• Python 3.8 or newer for native TONE3000 preset compilation.

• A compatible MCP client.

• A TONE3000 account and secret key for live TONE3000 tools.

• A NAM-compatible player and DAW/plugin host to use downloaded NAM models.

• AmpliTube 5 MAX only if you want to build the suggested AmpliTube chains.

Local AmpliTube search, recommendations, and troubleshooting can work without a TONE3000 credential. Live TONE3000 tools will return a configuration error, and recommendations will state that live candidates are unavailable.

Install and verify

git submodule update --init --recursive
npm install
Copy-Item .env.example .env

Open TONE3000 settings, generate API credentials, and put the secret key in .env:

TONE3000_SECRET_KEY=t3k_cs_replace_me

The secret key is a server-only Bearer credential. Never place it in browser code, a public repository, MCP tool output, logs, or a publicly reachable server.

Build and run the automated tests:

npm run build
npm test

If the submodule is missing, discovery and recommendation tools still build, but create_tone3000_plugin_preset returns a setup error until the builder is initialized.

Native TONE3000 preset delivery

create_tone3000_plugin_preset is intentionally a write tool: it creates a recipe and one or more preset artifacts under .cache/generated-presets. Discovery, recommendation, comparison, and troubleshooting tools remain read-only.

The tool accepts exact tone IDs and optional model-name regular expressions. It delegates compilation to the pinned external builder, checks the T3KB file signature, runs the builder's verifier, and only then returns the artifact. The current TONE3000 server credential is passed through the child process environment and is never placed on the command line or in tool output.

Presentation depends on the MCP transport:

• Stdio: the tool returns the absolute local path to each .t3kpreset file.

• HTTP: it also returns a link such as http://127.0.0.1:8787/presets/{artifactId}/{fileName}. That link is available only while the local HTTP server is running and only from the same computer by default.

The output folder can be changed with PRESET_OUTPUT_PATH. The server creates files but does not copy them into the TONE3000 plugin's preset directory or open the plugin.

Run locally with stdio

Stdio is the recommended transport for this MVP because it does not open a network listener:

npm run build
node dist/src/index.js

Connect to Codex or ChatGPT desktop

Codex CLI, the Codex IDE extension, and ChatGPT desktop can use locally configured MCP servers. Add the built stdio server with the CLI:

codex mcp add guitar-tone-assistant --env TONE3000_SECRET_KEY=t3k_cs_replace_me -- node C:\absolute\path\to\Tone3000mcp\dist\src\index.js

Alternatively, create a project-scoped .codex/config.toml in a trusted project:

[mcp_servers.guitar-tone-assistant]
command = "node"
args = ["C:/absolute/path/to/Tone3000mcp/dist/src/index.js"]
cwd = "C:/absolute/path/to/Tone3000mcp"
env_vars = ["TONE3000_SECRET_KEY"]

Do not put the secret value directly in config.toml; forward it from the local environment. Run codex mcp list or enter /mcp in a supported client to verify the connection.

See the official ChatGPT and Codex MCP configuration guide for current client instructions.

HTTP transport: local development only

The repository also includes a stateless Streamable HTTP transport:

npm run build
node dist/src/http.js

The endpoint is http://127.0.0.1:8787/mcp, and GET / returns a credential-safe health response. It can be inspected locally with:

npx @modelcontextprotocol/inspector@latest

Select Streamable HTTP and enter http://127.0.0.1:8787/mcp.

A shareable or published version must first authenticate MCP callers, verify authorization on every request, restrict its network and CORS policy, and replace the single shared TONE3000 credential with an appropriate per-user flow. OpenAI documents OAuth 2.1 as the expected authorization pattern for authenticated plugin MCP servers: OpenAI MCP authentication.

TONE3000 API behavior and publishing constraints

Verified against the official documentation on 2026-09-07:

• API v1 base: https://www.tone3000.com/api/v1.

• A secret key is a server-only Bearer credential.

• User-facing integrations should use OAuth 2.0 with PKCE.

• Search uses GET /tones/search; detail uses GET /tones/{id}; models use GET /models?tone_id={id}.

• A tone's API-provided url is returned rather than guessing a public page route.

• Model model_url downloads require the Bearer credential.

• The default limit is 100 requests per minute, while search is more heavily restricted.

• TONE3000 recommends its Select OAuth flow for production browsing.

• Free and commercial integrations have different endpoint and review requirements.

Review the current TONE3000 API documentation, design requirements, and commercial terms before publishing or monetizing an integration. The current global-secret search implementation is intended for trusted local evaluation, not a shared public service.

Preset Builder credit and update model

Native .t3kpreset compilation is powered by TONE3000 Preset Builder, created by Thomas Lennon and licensed under the MIT License. It is included as a Git submodule at vendor/tone3000-preset-builder, currently pinned to commit 0862e02f772657e4203d3f98164d851dc0ff63a0. See THIRD_PARTY_NOTICES.md and the builder's own license file for the full notice.

No compiler source was copied into this project. src/preset-builder/client.ts is a narrow adapter around the builder's public command-line interface. This separation means upstream fixes can be adopted by changing the Git submodule reference instead of copying files:

git -C vendor/tone3000-preset-builder fetch origin
git -C vendor/tone3000-preset-builder checkout <reviewed-commit-or-tag>
git add vendor/tone3000-preset-builder
npm run build
npm test

Review upstream changes and test generated files before advancing the pin. Consumers receive the reviewed version with git submodule update --init --recursive; they do not silently track the builder's latest branch.

AmpliTube catalog scope

The runtime catalog at src/data/amplitube5max.json contains all 435 models in IK Multimedia's AmpliTube 5 MAX v2 inventory, document version 5.10.4, updated 2025-03-27:

Official membership comes from IK's AmpliTube 5 MAX v2 gear inventory. Every runtime record carries the inventory version, source URL, category, and PDF page. The source-only extraction is stored in docs/research/amplitube-max-v2-inventory.json.

The v2 catalog was reconciled against the earlier 420-item research rather than replacing it blindly. The reconciliation matched 417 records, added 18, removed 3, and identified 3 renames. See docs/research/amplitube-max-v2-reconciliation.json and the earlier evidence set:

• docs/research/amplitube-max-cross-reference.md

• docs/research/amplitube-max-cross-reference.json

Inventory coverage and tone-depth coverage are deliberately distinguished. All 435 models are searchable, and 315 currently have a researched hardware basis. Detailed control lists, gain classifications, styles, and hand-tuned pairings are richer for the 19-record core recommendation set preserved in src/data/amplitube5max.curated.json. Empty tonal fields mean “not curated yet,” not “the model has no controls or uses.” Mapping states such as inferred, not-stated, and unresolved must not be presented as official hardware identities.

To rebuild after reviewing a newer official inventory, extract its factual name list and regenerate the merged catalog:

python scripts/extract-amplitube-inventory.py <official-inventory.pdf> docs/research/amplitube-max-v2-inventory.json
npm run catalog:build
npm run build
npm test

Official product reference: IK Multimedia AmpliTube 5.

User profiles

Profiles are optional local JSON records for guitars, pickups, tunings, interface, favorite amps/IRs, AmpliTube ownership, and monitoring equipment.

Saving a profile does not automatically cause recommend_tone_chain to load it. An MCP client must currently read the profile and pass relevant guitar, pickup, tuning, or workflow information into a recommendation request.

The profile store is designed for one trusted local process. It is not suitable for concurrent or multi-user hosting.

Project structure

src/index.ts                    stdio entry point
src/http.ts                     Streamable HTTP development entry point
src/server.ts                   MCP tool definitions and schemas
src/tone3000/                   TONE3000 API client, types, cache, and normalization
src/amplitube/                  Local AmpliTube search and types
src/recommendation/             Recommendation, comparison, and troubleshooting rules
src/preset-builder/             Adapter and types for the external preset compiler
src/profile/                    Local profile storage
src/data/amplitube5max.json     Generated 435-record MAX v2 runtime catalog
src/data/amplitube5max.curated.json Rich metadata for the core recommendation set
tests/                          Automated unit tests
docs/research/                  Catalog research and repository review notes
scripts/                        Repeatable inventory extraction and catalog merge
vendor/tone3000-preset-builder/ Pinned external compiler Git submodule

The service is intentionally modular: TONE3000 access is isolated from the recommendation engine, and another gear platform can be added alongside src/amplitube.

Current limitations and roadmap

The main work required before a public release is:

1. Add MCP caller authentication and authorization for non-local use.

2. Implement TONE3000 per-user OAuth/Select rather than sharing one server credential.

3. Validate all upstream API responses before caching or processing them.

4. Make profile storage safe for reserved IDs and concurrent writes.

5. Enrich the full AmpliTube catalog with each model's real control names, ranges, channels, modes, and collection ownership metadata.

6. Generate settings from those model-specific controls instead of the shared starter control vocabulary.

7. Make saved profiles influence recommendations automatically.

8. Add DAW- and NAM-player-aware routing instructions.

9. Add an explicit preview/confirmation step that converts a recommendation into a preset recipe automatically.

10. Add HTTP, malformed-response, profile-concurrency, and catalog-update tests.

For detailed review evidence, see docs/research/code-review-2026-09-07.md.

Status

This repository is suitable for local experimentation and MCP development and now has authoritative, versioned inventory coverage of AmpliTube 5 MAX v2. It is not currently suitable for anonymous public hosting, multi-user profile storage, or model-perfect instructions for every control on all 435 models.