fmod-mcp

Ein MCP-Server, der es einem KI-Coding-Agenten ermöglicht, FMOD Studio zu steuern – Audio importieren, Ereignisse erstellen, Instrumente verknüpfen, Banken erstellen – indem er über TCP (Port 3663) mit dem integrierten JavaScript-Scripting-Terminal von Studio kommuniziert.

Entwickelt für die Verwendung mit Claude Code, funktioniert aber mit jedem MCP-kompatiblen Client.

Anforderungen

• FMOD Studio 2.02+ (das Scripting-Terminal ist in den letzten Versionen stabil)

• Python 3.11+

• Eine laufende FMOD Studio-Instanz mit geöffnetem Zielprojekt

Installation

git clone https://github.com/jmperez127/fmod-mcp.git
cd fmod-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Registrierung bei Claude Code

Führen Sie dies innerhalb des geklonten fmod-mcp-Verzeichnisses aus (damit $(pwd) korrekt aufgelöst wird):

claude mcp add fmod -s user -- "$(pwd)/.venv/bin/python" -m fmod_mcp

Das -- beendet das Flag-Parsing von claude mcp add, sodass -m fmod_mcp als Argumente für Python behandelt wird. -s user registriert den Server für jede Claude Code-Sitzung auf Ihrem Computer; lassen Sie es weg für eine projektlokale Registrierung.

Alternativ, wenn Sie ein global aufrufbares Shim bevorzugen, installieren Sie es über pipx:

pipx install .
claude mcp add fmod -s user fmod-mcp

Überprüfung:

claude mcp list

Host/Port konfigurieren (optional)

Standardmäßig 127.0.0.1:3663. Überschreiben Sie dies mit Umgebungsvariablen:

export FMOD_MCP_HOST=127.0.0.1
export FMOD_MCP_PORT=3663

TCP-Scripting in Studio aktivieren

Das Scripting-Terminal von FMOD Studio lauscht standardmäßig auf TCP/3663. Falls es deaktiviert ist:

1. Öffnen Sie FMOD Studio

2. Edit → Preferences (oder FMOD Studio → Preferences unter macOS)

3. Suchen Sie nach Scripting / Terminal-Einstellungen

4. Aktivieren Sie den TCP-Listener und notieren Sie den Port

Schneller Rauchtest

Bei laufendem FMOD Studio und geöffnetem Projekt:

> ping
{ ok: true, version: "2.02.24" }

> list_banks
[ { path: "bank:/Master", guid: "...", name: "Master" }, ... ]

Typischer End-to-End-Prozess (Hinzufügen eines SFX)

> import_audio /absolute/path/to/my_sound.wav
{ guid: "abc...", name: "my_sound.wav", length: 0.84 }

> create_event event:/test/my_sound bank:/Master
{ guid: "def...", path: "event:/test/my_sound", bank: "bank:/Master", bus: null }

> add_single_sound event:/test/my_sound abc...
{ track_guid: "...", instrument_guid: "...", audio_file_guid: "abc...", length: 0.84 }

> save_project
{ ok: true, saved: true }

> build_banks
{ ok: true, built: true, banks: [...] }

Das neue Ereignis ist jetzt in Ihrem Spiel über die von Ihnen verwendete FMOD-Runtime abspielbar (z. B. FmodServer.play_one_shot("event:/test/my_sound") in Godot).

Dateien, die geschrieben werden

• ~/.cache/fmod-mcp/commands.log — jedes JS-Snippet, das an Studio gesendet wurde, mit Zeitstempel nach Anfrage-ID. Audit-Trail + Replay-Quelle.

Wenn etwas nicht funktioniert

Die FMOD Studio Scripting-API ist ungleichmäßig dokumentiert und einige Methoden-/Eigenschaftsnamen unterscheiden sich je nach Studio-Version. Wenn ein Tool fehlschlägt:

1. Überprüfen Sie ~/.cache/fmod-mcp/commands.log auf das exakte JS, das gesendet wurde

2. Fügen Sie es in das eigene Scripting-Fenster von Studio ein (Window → Scripting in der Studio-GUI) und iterieren Sie

3. Sobald es funktioniert, patchen Sie die entsprechende JS-Vorlage in fmod_mcp/tools/*.py

Für alles, was nicht durch ein benanntes Tool abgedeckt ist, verwenden Sie run_js:

> run_js return studio.project.model.Event.findInstances().length;
42

Layout

fmod_mcp/
├── studio_client.py   # TCP/3663 client — single persistent connection, request sentinels
├── server.py          # FastMCP tool registration, stdio transport
├── __main__.py        # python -m fmod_mcp
└── tools/
    ├── discovery.py   # ping, list_*, get_event
    ├── audio.py       # import_audio
    ├── events.py      # create_event, add_single_sound, set_event_property, assign_to_*
    ├── project.py     # save_project, build_banks
    └── escape.py      # run_js

Lizenz

MIT © 2026 jmperez127.