fmod-mcp

Un servidor MCP que permite a un agente de codificación de IA controlar FMOD Studio — importar audio, crear eventos, conectar instrumentos, compilar bancos — comunicándose con el terminal de scripting JavaScript integrado de Studio a través de TCP (puerto 3663).

Creado para su uso con Claude Code, pero funciona con cualquier cliente compatible con MCP.

Requisitos

• FMOD Studio 2.02+ (el terminal de scripting ha sido estable en las versiones recientes)

• Python 3.11+

• Una instancia de FMOD Studio en ejecución con el proyecto de destino abierto

Instalación

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

Registrar en Claude Code

Ejecuta esto desde dentro del directorio clonado fmod-mcp (para que $(pwd) se resuelva correctamente):

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

El -- finaliza el análisis de flags de claude mcp add, por lo que -m fmod_mcp se trata como argumentos para Python. -s user registra el servidor para cada sesión de Claude Code en tu máquina; omítelo para un registro local del proyecto.

Alternativamente, si prefieres un shim invocable globalmente, instálalo mediante pipx:

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

Verificar:

claude mcp list

Configurar host/puerto (opcional)

El valor predeterminado es 127.0.0.1:3663. Puedes sobrescribirlo con variables de entorno:

export FMOD_MCP_HOST=127.0.0.1
export FMOD_MCP_PORT=3663

Habilitar scripting TCP en Studio

El terminal de scripting de FMOD Studio escucha en TCP/3663 de forma predeterminada. Si está deshabilitado:

1. Abre FMOD Studio

2. Edit → Preferences (o FMOD Studio → Preferences en macOS)

3. Busca la configuración de Scripting / Terminal

4. Habilita el listener TCP y anota el puerto

Prueba rápida de funcionamiento

Con FMOD Studio en ejecución y un proyecto abierto:

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

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

Flujo típico de extremo a extremo (añadir un 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: [...] }

El nuevo evento ya se puede reproducir en tu juego a través del runtime de FMOD que utilices (por ejemplo, FmodServer.play_one_shot("event:/test/my_sound") en Godot).

Archivos que escribe

• ~/.cache/fmod-mcp/commands.log — cada fragmento de JS enviado a Studio, con marca de tiempo por ID de solicitud. Pista de auditoría + fuente de reproducción.

Cuando algo falla

La API de scripting de FMOD Studio está documentada de forma desigual y algunos nombres de métodos/propiedades difieren según la versión de Studio. Si una herramienta falla:

1. Revisa ~/.cache/fmod-mcp/commands.log para ver el JS exacto que se envió

2. Pégalo en la ventana de Scripting de Studio (Window → Scripting en la interfaz gráfica de Studio) e itera

3. Una vez que funcione, corrige la plantilla JS correspondiente en fmod_mcp/tools/*.py

Para cualquier cosa no cubierta por una herramienta con nombre, usa run_js:

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

Estructura

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

Licencia

MIT © 2026 jmperez127.