fmod-mcp

MCP-сервер, который позволяет ИИ-агенту для программирования управлять FMOD Studio — импортировать аудио, создавать события, подключать инструменты, собирать банки — путем взаимодействия со встроенным терминалом JavaScript-скриптов Studio через TCP (порт 3663).

Создан для использования с Claude Code, но работает с любым MCP-совместимым клиентом.

Требования

• FMOD Studio 2.02+ (терминал скриптов стабилен в последних версиях)

• Python 3.11+

• Запущенный экземпляр FMOD Studio с открытым целевым проектом

Установка

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

Регистрация в Claude Code

Запустите это изнутри клонированной директории fmod-mcp (чтобы $(pwd) корректно разрешался):

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

Символы -- завершают разбор флагов claude mcp add, поэтому -m fmod_mcp передается как аргументы для Python. Флаг -s user регистрирует сервер для каждого сеанса Claude Code на вашем компьютере; уберите его для локальной регистрации в рамках проекта.

Альтернативно, если вы предпочитаете глобально вызываемую оболочку, установите через pipx:

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

Проверка:

claude mcp list

Настройка хоста/порта (опционально)

По умолчанию используется 127.0.0.1:3663. Переопределите с помощью переменных окружения:

export FMOD_MCP_HOST=127.0.0.1
export FMOD_MCP_PORT=3663

Включение TCP-скриптинга в Studio

Терминал скриптов FMOD Studio по умолчанию прослушивает TCP/3663. Если он отключен:

1. Откройте FMOD Studio

2. Edit → Preferences (или FMOD Studio → Preferences в macOS)

3. Найдите настройки Scripting / Terminal

4. Включите TCP-прослушиватель, запишите порт

Быстрая проверка работоспособности

При запущенном FMOD Studio и открытом проекте:

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

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

Типичный сценарий (добавление одного 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: [...] }

Новое событие теперь можно воспроизвести в вашей игре через любую среду выполнения FMOD, которую вы используете (например, FmodServer.play_one_shot("event:/test/my_sound") в Godot).

Файлы, которые он записывает

• ~/.cache/fmod-mcp/commands.log — каждый фрагмент JS, отправленный в Studio, с отметкой времени по ID запроса. Журнал аудита + источник для повторного воспроизведения.

Если что-то идет не так

API скриптов FMOD Studio задокументировано неравномерно, и некоторые имена методов/свойств различаются в зависимости от версии Studio. Если инструмент выдает ошибку:

1. Проверьте ~/.cache/fmod-mcp/commands.log на наличие точного JS-кода, который был отправлен

2. Вставьте его в окно скриптов Studio (Window → Scripting в графическом интерфейсе Studio) и исправьте

3. После того как все заработает, обновите соответствующий JS-шаблон в fmod_mcp/tools/*.py

Для всего, что не покрывается именованным инструментом, используйте run_js:

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

Структура

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

Лицензия

MIT © 2026 jmperez127.