# flemcee
[](https://pypi.org/project/flemcee/)
[](https://pypi.org/project/flemcee/)
MCP server for FL Studio powered by the `flapi` Python client. It exposes
FL Studio control by executing Python inside FL Studio via Flapi.
See `/Users/tylertt/flemcee/WORKLOG.md` for an implementation summary and
`/Users/tylertt/flemcee/ROADMAP.md` for the future plan.
## Prerequisites
- `flapi` installed and working (FL Studio configured with Flapi scripts).
- FL Studio running with the Flapi server loaded.
- macOS: keep `flapi port-host` running while FL Studio is open.
## Install
```bash
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
```
## Run
Default MCP transport is streamable HTTP:
```bash
python -m flemcee
```
To use stdio transport:
```bash
FLEMCEE_TRANSPORT=stdio python -m flemcee
```
## Configuration
Environment variables:
- `FLEMCEE_TRANSPORT`: MCP transport (`streamable-http`, `stdio`, or `sse`).
- `FLEMCEE_REQ_PORT`: MIDI request port name (default: `Flapi Request`).
- `FLEMCEE_RES_PORT`: MIDI response port name (default: `Flapi Response`).
- `FLEMCEE_CONNECT_ON_START`: set to `true` to connect to FL Studio at startup.
- `FLEMCEE_LOG_LEVEL`: logging level (default: `INFO`).
- `FLEMCEE_HOST`: server host when supported by the MCP transport (default: `127.0.0.1`).
- `FLEMCEE_PORT`: server port when supported by the MCP transport (default: `8000`).
- `FLEMCEE_MOUNT_PATH`: optional base mount path for HTTP transports.
- `FLEMCEE_STREAMABLE_HTTP_PATH`: optional streamable HTTP endpoint path.
- `FLEMCEE_SSE_PATH`: optional SSE endpoint path.
- `FLEMCEE_GENERATE_TOOLS`: set to `true` to register per-function tools from stubs (default: `true`).
- `FLEMCEE_CURATED_TOOLS`: set to `true` to register curated higher-level tools (default: `true`).
## MCP Tools
- `fl_connect(force: bool = false)`
- `fl_disconnect()`
- `fl_status()`
- `fl_exec(code: str)`
- `fl_eval(expression: str)`
- `fl_call(target: str, args: list = [], kwargs: dict = {})`
- `fl_catalog(module: str | None = None, include_docs: bool = False)`
- `fl_symbol_lookup(symbol: str, include_docs: bool = False)`
- `fl_symbol_resolve(target: str, include_docs: bool = False)`
Curated tools (auto-generated at startup):
- `fl_session_summary()`
- `fl_transport_play()`
- `fl_transport_stop()`
- `fl_transport_record_toggle()`
- `fl_transport_set_loop_mode(mode: str | int)`
- `fl_transport_set_song_pos(position: float | int, mode: int = -1)`
- `fl_project_set_tempo(bpm: float)`
- `fl_channel_list(global_count: bool = False, use_global_index: bool = False)`
- `fl_channel_set(index: int, name: str | None, color: int | None, volume: float | None, pan: float | None, pitch: float | None, target_fx_track: int | None, use_global_index: bool = False)`
- `fl_channel_select(index: int, use_global_index: bool = False)`
- `fl_pattern_list(include_defaults: bool = False)`
- `fl_pattern_select(index: int)`
- `fl_pattern_rename(index: int, name: str)`
- `fl_sequencer_set_steps(channel_index: int, steps: list[int], value: bool = True, use_global_index: bool = False)`
- `fl_sequencer_clear_steps(channel_index: int, length: int = 16, use_global_index: bool = False)`
- `fl_mixer_list_tracks(max_tracks: int = 125)`
- `fl_mixer_set_track(index: int, volume: float | None, pan: float | None, mute: bool | None, solo: bool | None, arm: bool | None)`
- `fl_mixer_route(source_index: int, dest_index: int, enabled: bool = True, level: float | None = None, update_ui: bool = True)`
- `fl_plugin_list_params(index: int, slot_index: int = -1, limit: int = 64, use_global_index: bool = False)`
- `fl_plugin_set_param(index: int, param_index: int, value: float, slot_index: int = -1, use_global_index: bool = False)`
- `fl_plugin_next_preset(index: int, slot_index: int = -1, use_global_index: bool = False)`
- `fl_beat_make_hiphop(kick_channel: int, snare_channel: int, hat_channel: int, bars: int = 1, style: str = \"boom_bap\")`
- `fl_mix_balance_peaks(track_indices: list[int], target_peak: float = 0.8, mode: int = 2, min_volume: float = 0.0, max_volume: float = 1.0, max_change: float | None = 0.2)`
## MCP Resources
- `flstudio://catalog`
- `flstudio://module/{module}`
## Notes
- `fl_exec` and `fl_eval` run inside FL Studio's Python environment.
- Use `fl_call` for convenience (e.g. `target="transport.start"`).
- The API catalog tools read from `fl-studio-api-stubs`, providing signatures and documentation when available.
- When stub-based tool generation is enabled, each top-level FL Studio function is registered as a tool named `fl_<module>_<function>`.
## Examples
See `/Users/tylertt/flemcee/EXAMPLES.md` for complete workflows:
- “Listen to this project and do a mix”
- “Take this loop and sequence it out into a full hip hop beat”
