Skip to main content
Glama
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