@simpligen/mcp
v0.10.0
Published
MCP server for SimpliGen -- drive local/cloud AI image & video generation from an agent.
Readme
@simpligen/mcp
MCP server that lets an AI agent drive SimpliGen (local + cloud AI image/video generation). Requires the SimpliGen desktop app running and a pairing token (Settings -> Connect an agent).
Configure (Claude Code / Claude Desktop)
The easiest path is in the SimpliGen app: Settings -> Connect an agent, pick your client, and click Install (or copy the guided command). The manual config below is the fallback.
{
"mcpServers": {
"simpligen": {
"command": "npx",
"args": ["-y", "@simpligen/mcp"],
"env": { "SIMPLIGEN_TOKEN": "sg-agent-..." }
}
}
}Tools
list_capabilities, get_status, list_projects, create_project, upload_file, generate, get_job, wait_for_result, list_jobs, cancel_job, prepare_preset, get_result_image, wait_for_approval, get_app_context, fill_generate_form, open_screen, accept_character_base.
Approval flow (SimpliGen's in-app Assistant). A token the app issues for its own Assistant panel is flagged approvalRequired. With it, any call that queues a generation, renders or exports a film, runs a recipe, or deletes a character, product or outfit does not run. It returns awaiting_approval with a proposalId, and the user sees an approval card in the app. Call wait_for_approval(proposalId) (it long-polls in short rounds, like wait_for_result). It returns the real result once the user clicks Approve, or declined with the user's optional reason so you can adjust and propose again. For regenerate_character_base, the approved result carries a base job id: wait on it with wait_for_result, then call accept_character_base. Normal pairing tokens (Claude Desktop and other clients) never see this flow.
Screen tools. get_app_context returns what the user is looking at. fill_generate_form fills the visible Generate form and never presses Generate. open_screen navigates the app. They work for outside MCP clients too.
Video Studio (connector 0.5.0 or newer): list_films, create_film, get_film, update_film_settings, add_track, move_track, detect_tempo, add_clip, import_clip (0.8.1), update_clip, move_clip, trim_clip, remove_clip, apply_film_plan, set_fades, add_marker, set_export_range, render_clips, wait_for_renders, list_takes, use_take, export_film, list_locations, create_location, and the Wardrobe (0.10.0): list_wardrobe, create_outfit, remove_outfit. An agent can build a whole music video: a song, its tempo, clips on the bars, shots, renders and the export. With the film open in the Video Studio every change shows live and undoes with Ctrl+Z. They need the Video Studio in SimpliGen (SimpliGen 1.75 or newer). Since connector 0.8.0 they are always listed; without the studio each one answers studio_not_installed.
get_result_image returns a completed job's result image inline (a viewable image block) so the agent can display it in chat. Claude clients cap a tool result at ~1MB and only render base64 image blocks, so large renders are re-encoded to a full-resolution WebP preview (same dimensions; quality steps down, and only very large images are resized) that fits the cap. The uncompressed original file path is always included in the caption, so the agent keeps the full-quality artifact. Video results return the file path instead.
If your client does not forward env vars
Some MCP clients spawn the server without passing env through, and the connector
then reports missing_token however carefully the variable was set. Pass the token
as an argument instead, which every client can express:
{
"mcpServers": {
"simpligen": {
"command": "npx",
"args": ["-y", "@simpligen/mcp", "--token", "sg-agent-..."]
}
}
}--port works the same way. Both accept --name value or --name=value.
The environment is still the better route where it works: an argument is visible in the process list and an environment variable is not. Use this when the client leaves you no choice.
Env
SIMPLIGEN_TOKEN(required) -- pairing token from the app.SIMPLIGEN_API_PORT(optional) -- override the control-API port (else read from the app's discovery file).- Both can be given as
--token/--portarguments instead; see above. SIMPLIGEN_USERDATA_DIR/SIMPLIGEN_APP_NAME(optional) -- locate the app's data dir (CN variant / custom).
Manual smoke (for maintainers)
With the app running and a token issued:
SIMPLIGEN_TOKEN=<token> npx @modelcontextprotocol/inspector node src/bin.jsVerify: tool list appears; call get_status; call list_capabilities; call upload_file with a PNG path and confirm a handle is returned; call generate with a local preset and confirm a jobId; call wait_for_result and confirm a resultPath; call get_result_image and confirm the image renders inline.
