Skip to content
FlixMLFlixML Docs

MCP Server

FlixML ships an MCP server that puts your install directly inside an MCP host — Claude Desktop, Claude Code, Cursor, or anything else that speaks the protocol. The host gets tools for the whole pipeline, so you can say “make me a lighthouse at sunset, then animate it” and the agent does it on your GPUs.

It is scripts/mcp_server.py in the repo, written against the Python standard library only. There is nothing to install and nothing added to your environment.

Connect it

Section titled “Connect it”

Add FlixML to your host’s MCP config. In Claude Desktop that is claude_desktop_config.json; other hosts use the same shape.

{
  "mcpServers": {
    "flixml": {
      "command": "python",
      "args": ["/path/to/flixml/scripts/mcp_server.py"],
      "env": {
        "FLIXML_API_URL": "http://localhost:8191",
        "FLIXML_API_KEY_FILE": "~/.config/flixml/key"
      }
    }
  }
}
Variable Purpose
FLIXML_API_URL Your Studio API base URL. Defaults to http://localhost:8191.
FLIXML_API_KEY_FILE Path to a file holding the key, so it stays out of the host config. Accepts a bare key or a whole Authorization: Bearer <key> line.
FLIXML_API_KEY The key inline, if you’d rather not use a file.
FLIXML_MCP_TIMEOUT Seconds to wait on a Studio request. Defaults to 120.

Omit both key variables if your install doesn’t require keys. Give the host its own scoped key rather than an admin one — then it can only see what it made.

Restart the host after editing its config. FlixML’s tools should appear in its tool list; if they don’t, run the command yourself in a terminal and watch for an error on stderr.

What the host can do

Section titled “What the host can do”
Tool
list_workflows Every workflow your install can run, with its task, VRAM need and recent run times
list_nodes Your GPU nodes: roles, VRAM, what’s queued, whether they’re online
generate_image Text to image, or edit an existing image
generate_video Image to video, video to video, and lip-sync
last_frame Take a clip’s final frame as an image, to start the next shot where the last one ended
get_job Status and outputs, plus the workflow, models, LoRAs, seed and params behind a result
list_jobs Recent jobs and their status
search_media Search the media library by filename or prompt
upload_image Put a local file into Studio and get its filename back
list_characters Characters this key may use
create_project, create_scene, create_shot, set_shot_media Build a multi-shot movie
render_project, get_render Render it and collect the final video

The server also exposes two resources the host can read directly:

  • flixml://guide — the agent guide, served live by your install
  • flixml://openapi — your install’s OpenAPI schema

Both come from the running server rather than being baked into the MCP server, so the host sees your workflows, your nodes and your characters, not a generic list.

Notes

Section titled “Notes”

Generation is asynchronous. generate_image and generate_video return a prompt_id straight away and the render continues on the GPU node; the host collects the result with get_job. A video can take ten minutes or more, so expect the agent to come back to it later rather than sit and wait.

Run one video job per node at a time. list_nodes reports what each node already has queued.

Prefer the HTTP API?

Section titled “Prefer the HTTP API?”

Nothing here replaces the Agent API — the MCP server is a thin layer over the same endpoints. An agent that can make HTTP calls should read SKILL.md, which your install serves at /api/guide, and call the API directly.