# GWwise — Wwise MCP Server

**Connect an AI assistant to Audiokinetic Wwise for game-audio batch editing, project inspection, profiling, and audition.** GWwise is a local Model Context Protocol (MCP) server backed by the Wwise Authoring API (WAAPI).

[English](README.md) · [简体中文](README.zh-CN.md) · [Download Windows executable](https://github.com/WilliamWAudio/wwise-mcp-server/releases/latest) · [Workflows](#practical-workflows) · [Compatibility](docs/compatibility.md) · [Validation](docs/validation.md)

**Canonical project:** [WilliamWAudio/wwise-mcp-server](https://github.com/WilliamWAudio/wwise-mcp-server). Repository name: `wwise-mcp-server`; executable and MCP server name: `gwwise-mcp-server`; short name: **GWwise**. This is an independent community project, not an Audiokinetic product.

## What can I use it for?

- **Replace Wwise audio sources by name** without intentionally creating new Sound objects.
- **Batch rename and organize objects**, copy or move missing descendants, and synchronize Output Bus references by relative path.
- **Inspect a project with WAQL**, read properties and references, and discover the connected Wwise instance's actual API schemas.
- **Generate SoundBanks, sample Profiler data, and audition audio** through Wwise Authoring.
- **Subscribe to WAAPI events** instead of repeatedly querying the same state.

The public catalog exposes **45 MCP tools**: 44 definitions in [`knowledge/defs.json`](knowledge/defs.json), plus `wwise_connect` added by the server. Of these, **17 names start with `batch_`**. These are interface counts, not a benchmark or a claim that every workflow is one call.

## Why consider GWwise?

| Need | How this project approaches it | Boundary |
| --- | --- | --- |
| Simple Windows deployment | Official releases provide one executable; users do not need Python or Node.js to run it | Wwise Authoring with WAAPI is still required; obtain binaries from a trusted release |
| Repetitive authoring work | Purpose-built tools for source replacement, hierarchy synchronization, renaming, and routing | Some operations allow partial success; inspect each returned result |
| Version-aware requests | Dynamic function, topic, and schema discovery from the connected Wwise instance | Discovery is not proof of compatibility with every release; see [version evidence](docs/compatibility.md) |
| Fewer manual API payloads | Higher-level tools coexist with raw WAAPI and WAQL access | Raw calls can modify or delete content; there is no universal read-only enforcement mode |
| Agent operating guidance | Official binaries include the maintainer's tuned knowledge base | Public source builds use fallback instructions; source and knowledge licensing differ |

## Quick start: Windows executable

1. Download `gwwise-mcp-server.exe` from [GitHub Releases](https://github.com/WilliamWAudio/wwise-mcp-server/releases/latest). This is a **local stdio server**, not a hosted service to deploy to a cloud URL.
2. Open a **backed-up test copy** of your Wwise project.
3. Enable **Project → User Preferences → Wwise Authoring API**. Confirm the WAMP port; the usual default is `8080`.
4. Register the executable in an MCP-compatible client. Replace the example absolute path with your real path.

Claude Desktop / Claude Code configuration example (`claude_desktop_config.json` / `.mcp.json`):

```json
{
  "mcpServers": {
    "wwise": {
      "command": "C:/Tools/GWwise/gwwise-mcp-server.exe",
      "args": ["--wwise-host", "127.0.0.1", "--wwise-port", "8080"]
    }
  }
}
```

Cursor example (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "wwise": {
      "command": "C:/Tools/GWwise/gwwise-mcp-server.exe",
      "args": ["--wwise-port", "8080"]
    }
  }
}
```

Codex configuration example (`config.toml`):

```toml
[mcp_servers.wwise]
command = "C:/Tools/GWwise/gwwise-mcp-server.exe"
args = ["--wwise-host", "127.0.0.1", "--wwise-port", "8080"]
```

Client configuration locations and approval controls vary by client version. The server can start before Wwise is open and connects when a tool needs WAAPI. Its connection code may try nearby fallback ports: **verify the returned project and endpoint before any edit**, especially when multiple Wwise instances are open.

### First request: inspect, do not edit

> Connect to Wwise and report the connected application version and project identity. Query the selected objects and list available schemas. Do not change project objects, save the project, generate SoundBanks, delete files, start playback, or change the profiler session.

This is an instruction to the assistant, not a server-enforced permission boundary. A client that supports tool allowlists should expose only the needed inspection tools first.

## Practical workflows

These are **reproducible workflow guides**, not a claim that the scenarios were run successfully during this documentation update.

| Task | Guide | Useful starting tools |
| --- | --- | --- |
| Replace same-name WAV sources while preserving the existing Sound hierarchy | [Replace audio sources without creating new Sounds](docs/workflows/replace-audio-sources.md) | `waapi_query`, `list_local_audio_files`, `batch_replace_audio_by_name` |
| Review object properties, routing, references, and SoundBank inclusion | [Inspect and audit a Wwise project](docs/workflows/audit-project.md) | `waapi_query`, `waapi_get_schema`, `get_soundbank_inclusions` |
| Sample runtime state and preview an Event | [Profiler sampling and controlled audition](docs/workflows/profile-and-audition.md) | `profiler_capture`, `transport_play`, `transport_control` |

Example requests:

- “List every Sound under Weapons whose volume is below -10 dB. Report the GUID and path; do not modify anything.”
- “Compare the selected subtree with these same-name WAV files. Show the proposed matches first; do not replace audio until I confirm.”
- “Preview moving missing descendants from this source to this target. Use an explicit `preview_only: true` where the tool supports it.”
- “Subscribe to object name changes, wait for an event, then unsubscribe when finished.”

## Tool catalog

| Domain | Tools |
| --- | --- |
| Core | `waapi_call`, `waapi_query`, `wwise_connect` |
| Local files | `list_local_audio_files`, `create_path_if_not_exists`, `get_project_languages` |
| Batch rename | `batch_rename_lowercase`, `batch_rename_titlecase`, `batch_rename_uppercase`, `batch_rename_find_replace`, `batch_rename_add_prefix`, `batch_rename_add_suffix` |
| Batch structure | `batch_delete`, `batch_smart_delete`, `batch_delete_unused_descendants`, `batch_convert_type`, `batch_set_property`, `batch_move`, `batch_get_children_by_type` |
| Structure synchronization | `batch_copy_missing_descendants`, `batch_move_missing_descendants`, `batch_sync_output_bus_by_relative_path` |
| Audio sources | `batch_replace_audio_by_name`, `cleanup_unused_originals_files` |
| Introspection | `waapi_list_functions`, `waapi_list_topics`, `waapi_get_schema` |
| SoundBank | `generate_soundbanks`, `get_soundbank_inclusions` |
| Profiler | `profiler_capture` |
| Remote connection | `remote_list_consoles`, `remote_connect`, `remote_disconnect` |
| Wwise UI | `ui_get_selection`, `ui_list_commands`, `ui_execute_command` |
| Subscriptions | `waapi_subscribe`, `waapi_poll_events`, `waapi_wait_for_event`, `waapi_list_subscriptions`, `waapi_unsubscribe` |
| Health / audition | `wwise_get_info`, `transport_play`, `transport_control`, `transport_list` |

The authoritative parameter definitions are in [`knowledge/defs.json`](knowledge/defs.json) and [`src/bin/mcp_server.rs`](src/bin/mcp_server.rs). Inspect the schema instead of assuming similarly named tools have identical options.

## Safety and limitations

- **Back up the project and Originals before writes.** Query and confirm the intended project, GUIDs, scope, and changes first.
- **Preview is tool-specific.** Explicitly set `preview_only` when supported. `batch_replace_audio_by_name` and raw `batch_delete` do not provide the same preview contract.
- **Undo groups are not transactions.** Batches can report per-item failures or leave partial changes. Follow-up routing work may use another undo group. Do not promise a single Ctrl+Z reverses every workflow.
- **Disk changes are a separate risk.** `cleanup_unused_originals_files` can permanently delete files; Wwise Undo does not recover them. A preview can also write a report. Do not enable cleanup as part of routine inspection.
- **Profiler capture and audition affect sessions.** Sampling may enable profiler data, and playback tools produce audible sound. Get permission before either, and verify the final state.
- **The default endpoint is local, not an authorization sandbox.** Host arguments and connection tools can select other endpoints. Keep WAAPI on a trusted network. The AI client has its own data and privacy policies.
- **Schema discovery does not guarantee correct edits or audible results.** Wwise versions, structure, languages, plugins, and client behavior still need testing.

## Compatibility and evidence

The maintainer previously reported use across Wwise 2019–2025; the repository description separately mentioned 2021 and 2024. **Exact-build evidence is not yet published in this checkout**, so these are not presented as a verified per-version support matrix. See [compatibility](docs/compatibility.md) for recording a run.

The source contains **175 test cases** across unit, definition-contract, knowledge-text routing-contract, protocol, and live-Wwise suites. This does **not** mean 175 live-Wwise tests: there are nine live test functions, and some tests return early when Wwise or the private knowledge base is absent. A green aggregate alone is not proof of E2E coverage. See [validation and reproduction](docs/validation.md).

## Build from source

Install a Rust toolchain and the platform's native build prerequisites, then run:

```sh
cargo build --release
```

The Windows executable is `target/release/gwwise-mcp-server.exe`. A source build has the same public tool definitions but fallback instructions because `knowledge/base.txt` is intentionally absent. Do not infer non-Windows support or a minimum Rust version from this command; see [compatibility](docs/compatibility.md).

Documentation and metadata checks for contributors (Node.js required only for this check, not for running GWwise):

```sh
node scripts/check-docs.mjs
```

## Distribution and discovery

- [Windows EXE releases](https://github.com/WilliamWAudio/wwise-mcp-server/releases/latest) remain the direct installation path.
- [MCPB packaging and Registry preparation](docs/distribution/README.md) describe an optional bundle. A raw `.exe` is **not** an MCPB package. No new Registry publication is claimed by these files.
- [`glama.json`](glama.json) identifies the maintainer for directory metadata; it does **not** claim ownership verification or directory review is complete.
- [Maintainer discovery checklist](docs/discovery.md) covers repository About/topics, directory corrections, public evidence, and genuine community examples.

## License and project ownership

- **Public source code, tool definitions, and public documentation: MIT.** See the standard root [`LICENSE`](LICENSE).
- **Tuned knowledge base (`knowledge/base.txt`) and that content embedded in official binaries: proprietary.** The original free personal/commercial use and restrictions remain in [`knowledge/LICENSE`](knowledge/LICENSE). Do not describe the entire official binary as MIT-licensed.
- GWwise does not include Wwise or grant rights to Wwise, third-party plugins, or your audio assets.

Maintainer: [WilliamWAudio / william.wang](https://github.com/WilliamWAudio). Report reproducible problems in [GitHub Issues](https://github.com/WilliamWAudio/wwise-mcp-server/issues), including the GWwise version, exact Wwise build, operating system, task, and redacted error. Do not post private project paths, credentials, or copyrighted audio without permission.