FlMCP
by w1zzyakik
README.md
<img src="assets/banner.svg" alt="FlMCP — MCP-сервер для FL Studio" width="100%">
# FlMCP — MCP-сервер для FL Studio
Управление FL Studio из MCP-клиента (opencode, Claude Desktop, Cursor, ...). Внутрь
FL Studio ставится небольшой скрипт MIDI-контроллера, сервер общается с ним по
локальному TCP (`127.0.0.1:7777`), а скрипт выполняет код прямо в FL — в том же
интерпретаторе, где живёт всё её scripting API. Поэтому доступно всё, что FL открывает
своим скриптам: транспорт, микшер, каналы, плагины, паттерны, плейлист, окна, undo.
## Что умеет
| Инструмент | Что делает |
|---|---|
| `fl_eval` | Выполняет **любой** Python в FL Studio и возвращает результат в JSON: `channels`, `mixer`, `plugins`, `patterns`, `playlist`, `transport`, `arrangement`, `ui`, `general`, `device`, `utils`, `screen`, `midi` уже импортированы. Возвращается значение последнего выражения, а после блока операторов — `null`. |
| `fl_repl` | То же, но переменные живут между вызовами — удобно, когда работа идёт в несколько шагов. |
| `fl_api` | Справка по API **этой** версии FL: модули, сигнатуры, полные докстринги, вытащенные из живой FL Studio. |
| `fl_project` | Снимок проекта одним куском: версия, темп, позиция, паттерны, каналы, микшер с плагинами, треки плейлиста, открытые окна. |
| `fl_piano_roll` | Пишет ноты в piano roll выбранного канала (`[[нота, начало, длина, velocity], ...]`). Piano roll откроется сам, если закрыт. |
| `fl_window` | Открывает окно (микшер, плейлист, piano roll, браузер, channel rack) или нажимает пункт меню: `path=["File"], target="Save"`. |
| `fl_help` | Шпаргалка без обращения к FL: инструменты, как писать код, подводные камни API, рецепты. |
| `fl_screenshot` | Скриншот окна FL Studio. `list=True` показывает список окон, `title` выбирает нужное. |
## Требования
* Windows и FL Studio 20.8+ (проверено на FL Studio 2026).
* Python 3.10+ с пакетами `mcp` и `pillow`.
* Виртуальный MIDI-порт, например [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html).
Скрипт-мост загружается как MIDI controller script, а этот тип скриптов FL Studio
вешает только на MIDI-вход, без порта его просто не видно в списке.
## Установка
```powershell
cd F:\FlMCP\FlMCP
py -3.11 -m pip install -r requirements.txt
.\install.ps1
```
`install.ps1` кладёт в `Documents\Image-Line\FL Studio\Settings\Hardware` набор файлов с
одним и тем же именем **FlMCP**:
* `device_FlMCP.py` — собственно скрипт-мост (плюс `helpers.py` рядом);
* `FlMCP.ini` — файл настроек;
* `FLMCP.zip` — тот же комплект архивом.
FL Studio ищет MIDI-контроллер именно так — по паре `device_<имя>.py` + `<имя>.ini`, и
имена должны совпадать до буквы. Если папка называется `FLMCP`, а `device_FlMCP.py` +
`FlMCP.ini` лежат внутри — FL молча пропускает её, и ни в списке, ни в логах ничего не
появляется. В списке `Controller type` устройство называется **FlMCP** (имя из заголовка
`# name=` внутри скрипта).
Скрипт piano roll (`FLMCP_Write.py`) уезжает в `Settings\Piano roll scripts`, с уже
подставленными путями. Если папка FL Studio перенесена, добавьте `-FlUser "D:\FL Studio"`.
Дальше в FL Studio:
1. Создайте порт в loopMIDI и перезапустите FL Studio.
2. Options → MIDI settings → INPUT: включите *Enable* у порта, в поле *Controller type*
выберите **FlMCP** (там же, где `AKAI FL Studio Fire`, `Novation FLkey`, ...).
3. Проверка на живом FL Studio: `py -3.11 tests/live.smoke.py`.
Если FL Studio не грузит скрипт, он молчит: в окне настроек остаётся тот же список, а
порт `7777` закрыт. Тогда смотрите `FLMCP_load.txt` в `Settings\Hardware` рядом со
скриптом — он пишет время импорта или traceback и появляется только после того, как
FL запустил контроллер.
Сразу после этого лучше сделать `fl_project` — если ответ пришёл, мост жив, и можно
идти дальше. Перезапускать FL Studio нужно только после правки скриптов на диске.
Если раньше в FL Studio стоял старый `fl-studio-mcp` (karl-andres), его папка и
служебные JSON остаются лишними. Их убирает
```powershell
py -3.11 tools/clean_old_mcp.py --yes
```
Там есть и мелочи для отладки: `tools/fl_log.py` ищет в логах FL Studio строки про
`FlMCP`, `tools/fl_click.py` жмёт пункт меню через живой мост.
## Запуск
Сервер — обычный stdio MCP-сервер: `py -3.11 server.py`.
opencode (`opencode.json`):
```json
"fl-studio": {
"type": "local",
"command": ["py", "-3.11", "F:/FlMCP/FlMCP/server.py"],
"enabled": true
}
```
Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"fl-studio": {
"command": "py",
"args": ["-3.11", "F:/FlMCP/FlMCP/server.py"]
}
}
}
```
Порт моста меняется переменной окружения `FLMCP_PORT` (по умолчанию 7777) — и у
сервера, и у скрипта-моста.
## Примеры
```python
# что открыто
[ui.getVersion(4), ui.getProgTitle(), mixer.getCurrentTempo()]
# темп и транспорт
mixer.setCurrentTempo(128.0)
transport.setSongPos(16 * midi.PPQ) # 16-й такт
transport.start()
# громкость всех каналов на 70%
for i in range(channels.channelCount()):
channels.setChannelVolume(i, 0.7)
# параметр 3 плагина в первом слоте инсерта 1 на 50%
plugins.setParamValue(0.5, 3, 1, 0)
# плейлист и микшер
playlist.setTrackName(0, "drums")
[mixer.getTrackName(i) for i in range(8)]
```
```python
# ноты в piano roll выбранного инструмента
fl_piano_roll([(60, 0, 96, 100), (64, 96, 96, 90), (67, 192, 192, 80)])
```
Про API FL Studio стоит помнить пару вещей:
* порядок аргументов местами необычный: `plugins.setParamValue(value, paramIndex,
index, slotIndex, pickupMode, useGlobalIndex)`, `plugins.getPluginName(index,
slotIndex, userName, useGlobalIndex)`, `channels.setChannelVolume(index, volume,
pickupMode, useGlobalIndex)`;
* каналы (`channels.*`) и микшер (`mixer.*`) нумеруются отдельно;
* цвета FL хранит как `0xBBGGRR` — в `helpers` есть `helpers.rgb(r, g, b)` и
`helpers.color(value)`;
* код выполняется в потоке интерфейса FL Studio, поэтому бесконечный цикл положит
не только сервер, но и саму FL Studio.
## Ограничения
* **Плагины нельзя загрузить** через API — ни VST, ни встроенные. Их добавляют через
меню: `fl_window` умеет нажимать пункты, но выбор нужного плагина в длинном списке
надёжнее сделать руками.
* **Ноты piano roll нельзя прочитать** из MIDI controller script, FL даёт к ним доступ
только скриптам piano roll. Запись идёт через связку: контроллер кладёт задание рядом
с `FLMCP_Write.py`, нажимает пункт меню, FL запускает скрипт между кадрами, ответ
приходит файлом на следующем кадре. Читать ноты можно в самом скрипте piano roll,
но не из `fl_eval`.
* **Скрипт-мост перезагружается вместе с FL Studio**: после правки `device_FlMCP.py`
или `helpers.py` FL нужно перезапустить.
* **Скриншот**: FL Studio рисует через GPU, и `PrintWindow` может вернуть чёрный кадр.
Тогда сервер снимает экран и выводит окно на передний план — в этот момент окно не
должно быть перекрыто.
* `fl_eval` и `fl_repl` — это произвольный код в FL, ограничений по API нет; если код
завис, до перезапуска FL Studio отвечать будет некому.
* Не все версии FL Studio одинаковы: то, что было в 20.8, в 2026 могло отрасти новыми
аргументами. `fl_api` показывает именно вашу версию.
## Самопроверки
Требует запущенной FL Studio только последний:
```powershell
py -3.11 tests/controller.selfcheck.py # скрипт-мост против фейкового FL API (сокет + OnIdle)
py -3.11 tests/server.selftest.py # инструменты MCP против фейкового контроллера
py -3.11 tests/stdio.py # MCP-протокол: handshake, tools/list, tools/call
powershell -File tests/capture.selfcheck.ps1 # PrintWindow на живом окне (блокнот)
py -3.11 tests/live.smoke.py # живой FL Studio: всё по кругу
```
## Файлы
```
server.py MCP-сервер: TCP-мост с таймаутами, инструменты, скриншот окна
controller/device_FlMCP.py скрипт MIDI-контроллера для FL Studio: сокет, фоновые задания
controller/helpers.py удобства для fl_eval и piano roll, нажатия меню
controller/FLMCP_Write.py скрипт piano roll: пишет ноты по заданию
install.ps1 раскладывает скрипты по папкам FL Studio
tests/ самопроверки без FL Studio и живой смоук-тест
tools/ чистка следов старого mcp, логи, нажатия меню
assets/banner.svg шапка README
```
## Лицензия
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues