wwise-mcp

<h1 align="center">🎚️ wwise-mcp</h1>

<p align="center"><b>Talk to Wwise in plain English.</b><br> An MCP server that lets Claude drive <a href="https://www.audiokinetic.com/">Wwise</a> over WAAPI — audit your project, batch-edit, wire up events, and catch broken references, straight from a chat box.</p>

<p align="center"> <img alt="MIT License" src="https://img.shields.io/badge/license-MIT-green"> <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue"> <img alt="Wwise 2021.1+" src="https://img.shields.io/badge/Wwise-2021.1%2B-orange"> <img alt="Tests" src="https://img.shields.io/badge/tests-84%20passing-brightgreen"> <img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-blueviolet"> </p>

You:    "These 8 gunshots — make them playable in-game, per our conventions."

Claude:  ✅ converted   ✅ wrapped in a Random container   ✅ created 8 Play_ events
         ✅ routed to the SFX bus   ✅ added to the Main SoundBank
         (preview shown first · one Ctrl+Z undoes the whole thing)

Sound designers burn hours in plumbing mode — naming, building events, dragging folders, hunting "why is there no sound?". wwise-mcp hands all of that to the AI so you stay in your ears. Read the sound-designer's workflow →

✨ Why you'll want this

• 🩺 Catches real bugs. Events not in any SoundBank, empty sounds, and the classic code calls AK_Reload but Wwise has AK_Relod typo — pinpointed to the exact file:line.
• ⚡ One-shot flows. "Onboard this batch" runs convert → container → events → bus → bank in a single sentence. "Check everything and fix what's safe" audits then fixes.
• 🛡️ Safe by design. Every write previews first and undoes in one Ctrl+Z. It never touches the risky stuff (duplicates, empty sounds) without you.
• 🎧 Stays out of your art. It does the plumbing; mixing, sound choice, and feel stay yours.
• 🔌 20 tools, every one live-validated against real Wwise 2024.1 — not vaporware.

Setup

1. In Wwise: User Preferences → enable Wwise Authoring API (WAMP, default port 8080), then open a project.
2. Install:

   python3.12 -m venv .venv && . .venv/bin/activate && pip install -e .
   

3. Register with your MCP client (stdio). Use the absolute path to the venv entry point so it works without activating the venv first. For Claude Code:

   claude mcp add wwise -- /Users/inl/wwise-mcp/.venv/bin/wwise-mcp
   

   Or in an MCP client config JSON:

   { "mcpServers": { "wwise": { "command": "/Users/inl/wwise-mcp/.venv/bin/wwise-mcp" } } }
   

Tools

All 20 tools are live-validated against Wwise v2024.1.13. Write tools use a two-step mode="plan" (preview + token) → mode="apply" (execute, undoable) flow.

For how this fits a sound designer's actual day, see WORKFLOW.md.

One-shot flows (compose the building blocks — start here)

Tool	What it does
wwise_onboard_assets	Make sounds playable in one call: conversion → container → Play events → output bus → SoundBank (dry-run preview, then execute)
wwise_fix_all	Audit, then auto-fix the fixable (rename / bank / bus) and flag the rest for a human

Read / inspect

Tool	What it does
wwise_status	Connection / open-project health check
wwise_compat_check	Report Wwise version + which tools work on it (run first on a new version)
wwise_query	Read-only WAQL query (capped results)
wwise_inspect	Full property/reference dump of one object (by GUID, path, or name)
wwise_audit	Health checks: no Output Bus, empty container, empty sound, event-not-in-SoundBank, duplicate name
wwise_naming_check	Flag names with whitespace / non-ASCII / not matching a regex
wwise_bus_stats	Objects-per-Output-Bus overview
wwise_audio_file_check	Sources missing an original file / shared source paths
wwise_unity_check	Diff Unity C# PostEvent("X") calls against actual Wwise events

Document

Tool	What it does
wwise_export_docs	Markdown audio-design doc (summary, event list, Mermaid bus tree)

Write (plan/apply)

Tool	What it does
wwise_set_properties	Batch property edit (volume, output bus, …)
wwise_create_events	Auto-create Play_<Sound> events for sounds that lack one
wwise_rename	Batch rename via a transform (default spaces_to_underscores)
wwise_create_container	Wrap objects into a new container and move them in
wwise_assign_shareset	Batch-assign an Attenuation / Conversion ShareSet
wwise_move	Reparent objects under a target parent
wwise_soundbank_assign	Add objects to a SoundBank's inclusion list

Action

Tool	What it does
wwise_soundbank_generate	Generate SoundBanks to disk + error-log summary

Write tools show exactly what will change before anything is written, and each batch is one Ctrl+Z to undo.

Not yet implemented

• RTPC/Switch wiring — deferred: the @RTPC curve-object structure could not be cleanly validated via WAAPI in this environment, so a write op was not shipped rather than ship an unvalidated mutation. See docs/superpowers/notes/.

Compatibility

Requires Wwise 2021.1+ (the version that introduced WAQL, which most tools use). Run wwise_compat_check first on any untested version to see what works.

Wwise version	Status	Notes
2024.1.13	✅ verified	All tools live-validated
2021.1 – 2023.x	🟢 expected	WAQL present, core APIs stable — please report via an issue
< 2021.1	❌ unsupported	No WAQL; query-based tools return a clear version error

Help expand this matrix: see CONTRIBUTING.md — capturing your version takes ~5 minutes and no coding (python scripts/capture_fixtures.py → PR).

Tests

pytest -m "not integration"   # unit + contract (runs across all version fixtures) — no Wwise needed
pytest -m integration         # requires a running Wwise + open project

Design & plans

• Design spec: docs/superpowers/specs/2026-06-13-wwise-mcp-design.md
• Foundation plan: docs/superpowers/plans/2026-06-13-wwise-mcp-foundation.md
• Open WAAPI questions: docs/superpowers/notes/waapi-precondition-findings.md