Skip to main content
Glama

🎬 omnicinema-mcp

A local asset-creation engine exposed as a Model Context Protocol (MCP) server. Repository: https://github.com/joeshwoa/omnicinema-mcp

One local server that plans, designs, generates and edits production assets:

  • 🧠 Persona consultation β€” a Director of Photography, Graphic Designer, Voice Director and Music Producer compile a prompt strategy (positive/negative prompt, palette, lens, BPM/key/structure, pacing) before anything is generated.

  • πŸ–ΌοΈ Offline design engine β€” logos (emblem, monogram, wordmark, horizontal lockup; with reversed and icon variants), flat vector illustrations, and device-framed UI mockups as clean SVG (+ PNG), with no key and no network. Photos/textures via image APIs with your own key.

  • πŸŽ™οΈ Audio β€” narration via your system's TTS offline (or an HF TTS model), composed + synthesized soundtracks in seven genres (stereo WAV + editable multi-track MIDI), and procedural sound effects.

  • 🎞️ Video pipeline β€” one-line idea β†’ coherent multi-scene screenplay with shot-to-shot continuity β†’ stock footage (Pexels / Pixabay / Unsplash) or an offline storyboard animatic β†’ a frame-accurate edit with dissolves, Ken Burns motion, captions, a ducked soundtrack β†’ MP4 via Remotion or ffmpeg.

  • πŸ›‘οΈ Budget guard β€” persistent free-tier tracking; generative calls halt with a cost breakdown until the user approves.

  • πŸ”Œ Local REST API β€” token-authed, 127.0.0.1-only, so other local tools can request assets.

  • πŸ”­ Review-only discovery β€” finds candidate providers on public catalogs and queues them for a human; never integrates anything by itself.


What you get without any keys (honest version)

Capability

Offline result

Quality notes

Logo / vector art / UI mockup

Real SVG + PNG designs

Deterministic, brief-driven, professional-looking flat design. Text uses system fonts (Poppins β†’ Helvetica β†’ DejaVu fallbacks), so letterforms vary slightly by machine; convert text to outlines in a vector editor for final brand use.

Cinematic photo / texture

A clearly labelled placeholder

Not a photo. Needs an image API (HF_IMAGE_MODEL / REPLICATE_IMAGE_MODEL) + generative:true.

Voiceover

Real speech via say (macOS), pico2wave, ffmpeg's built-in flite, or espeak-ng

Intelligible (verified by transcribing it with Whisper) but clearly synthetic. With no TTS engine installed you get a timing tone that the tool labels NOT SPEECH. For a natural voice use HF_TTS_MODEL + generative:true.

Soundtrack

Composed & synthesized stereo WAV + multi-track MIDI

Real arrangement (chords, bass, drums, melody, section dynamics), mastered to about βˆ’14 LUFS with no clipping. It is a synth demo, not a studio recording; the MIDI is there to re-voice in a DAW.

Sound effects

13 procedural recipes (whoosh, rain, thunder, wind, ocean, impact, riser, click, ding, beep, fire, footsteps, heartbeat)

Good for placeholders/transitions; real recordings via Freesound with a key.

Video

An animatic: storyboard frames per shot with camera-matched motion, title card, captions, music, narration β†’ MP4

Real footage needs a stock key (free) or a generative video model (paid/quota).

Related MCP server: multimodal-mcp

Scope & ethics

Everything uses official, documented APIs with your own keys, within each service's Terms. It does not reuse browser sessions, scrape web UIs (Seedance, Higgsfield, Suno, Udio…), or auto-integrate code found online. If a service has no first-party API you can get a key for, it is out of scope.


Requirements

  • Node.js β‰₯ 18.17.

  • Recommended system tools (all optional, each unlocks something):

    • ffmpeg β€” renders MP4 without Remotion, measures media, normalizes TTS loudness, rasterizes SVG (if built with librsvg) and provides the flite voice.

    • rsvg-convert (librsvg2-bin / brew install librsvg) β€” PNG export of every SVG.

    • espeak-ng (Linux) β€” offline narration if neither say nor ffmpeg-flite is available.

    • Remotion toolchain β€” npm run setup:render (downloads a headless Chrome on first render).

Install

git clone https://github.com/joeshwoa/omnicinema-mcp.git
cd omnicinema-mcp
npm install            # core server (installs optional Remotion too unless you pass --omit=optional)
npm run build          # compile to dist/
npm run setup:render   # optional: install the pinned Remotion render toolchain

All runtime output lives under CINEMA_ROOT (default: the repo folder). Point it at an external drive to keep caches and renders off your system disk.

Register as an MCP server

Claude Desktop β€” see examples/claude_desktop_config.json:

{
  "mcpServers": {
    "omnicinema": {
      "command": "node",
      "args": ["/absolute/path/to/omnicinema-mcp/dist/index.js"],
      "env": { "CINEMA_ROOT": "/absolute/path/to/omnicinema-mcp" }
    }
  }
}

Claude Code: claude mcp add omnicinema -- node /absolute/path/to/omnicinema-mcp/dist/index.js

Keys (all optional)

cp .env.example .env   # fill in ONLY the keys you have

Variable

Enables

Network / cost

PEXELS_API_KEY / PIXABAY_API_KEY / UNSPLASH_ACCESS_KEY

Stock video/photos in run_cinema_pipeline

Free APIs; used automatically when set (stock:false to stay offline)

FREESOUND_API_KEY

Real SFX recordings (generate_sfx + generative:true)

Free API

HUGGINGFACE_API_TOKEN + HF_IMAGE_MODEL / HF_TTS_MODEL / HF_MUSIC_MODEL / HF_VIDEO_MODEL

Photos, natural voice, MusicGen, video

Quota / paid, only with generative:true

REPLICATE_API_TOKEN + REPLICATE_IMAGE_MODEL / REPLICATE_MUSIC_MODEL / REPLICATE_VIDEO_MODEL

Same, via Replicate

Paid, only with generative:true

FAL_API_KEY + FAL_VIDEO_MODEL

Video via fal.ai

Paid, only with generative:true

ANTHROPIC_API_KEY

Optional screenplay prose polish (1 call per run; enrich:false to skip)

Paid

Model ids are yours to choose, so new models work without code changes. Behaviour toggles: CINEMA_TTS=off|say|pico2wave|flite|espeak-ng, CINEMA_DISABLE_REMOTION=1 (force the ffmpeg renderer), CINEMA_DISABLE_RASTER=1, LIMIT_<PROVIDER>_<DAILY|WEEKLY|MONTHLY>=n.

Tools (15)

Every tool's text output ends with the files it wrote and next steps; a JSON block follows for programs.

Tool

Use it to…

Network / money

run_cinema_pipeline

Turn an idea into a video. Start with dry_run:true to get the screenplay, shot list, providers and a cost estimate instantly.

Stock APIs if keys set; generative:true spends quota

compile_montage

Finish an interactive_montage project or re-cut any project (reorder via montage-order.json, swap clip files).

None

generate_image

Logo, vector art, UI mockup (offline SVG+PNG), photo/texture (API).

Only photo/texture with generative:true

generate_voiceover

Speak a script (offline TTS or HF TTS).

Only with generative:true

generate_soundtrack

Compose music in a genre, optionally to a length (durationSeconds).

Only with generative:true

generate_sfx

Sound effect / ambience.

Freesound with generative:true

consult_personas

Preview the compiled brief without generating.

None

check_limits

See free-tier usage per provider.

None

list_providers

See which providers are configured.

None

install_dependencies

Preview (consent:false) or run (consent:true) ffmpeg/Blender/Remotion installs.

Installs only with consent

discover_providers / approve_suggestion

Queue candidate providers for review / catalogue one (added disabled).

Public catalog search

ipc_start / ipc_status / ipc_stop

Local REST API for other tools (for a long-running service use npm run ipc; devuniverse-mcp fetches assets from its POST /generate).

Localhost only

Typical flow

  1. run_cinema_pipeline { prompt, dry_run: true } β†’ show the user the shot list and spend (usually "Nothing").

  2. run_cinema_pipeline { prompt, narration, soundtrack: true, musicStyle } β†’ MP4 path + screenplay + timeline.

  3. Optional: edit montage-order.json or replace clip files in the project folder β†’ compile_montage { projectId }.

How the video is built

  • Screenplay: the idea is parsed into subject / action / setting / story element; the film gets one lighting look (e.g. dusk β†’ storm night β†’ grey dawn), scenes follow an arc (setup β†’ inciting β†’ climax β†’ resolution), shots follow film grammar (establishing β†’ medium β†’ close). Each shot's opening frame is identical to the previous shot's closing frame, camera moves are derived from the framing change, and screen direction is held. screenplay.md is human-readable.

  • Footage: per shot, the configured stock providers are searched with short, specific queries; hits are ranked by orientation, duration and resolution, never reused, downloaded, and licensed in attributions.txt. Unfilled shots get storyboard frames.

  • Edit: hard cuts inside a scene, true crossfades between scenes, Ken Burns motion matching the camera move, title card, captions from the narration, soundtrack fitted to the cut and ducked under the voice, fade out. Rendered by Remotion (remotion/compositions/CinemaTimeline.tsx) or, without it, by an equivalent ffmpeg filter graph.

Output layout

assets/                      # standalone assets (<subject>_<kind>.svg/.png/.wav/.mid)
projects/<id>/               # screenplay.{md,json}, timeline.json, clips, audio, attributions.txt, manifest.json
output/<id>.mp4              # rendered video
data/usage-limits.json       # budget guard database   (gitignored)
data/review-queue.json       # discovery queue         (gitignored)
data/ipc-token.txt           # IPC bearer token, 0600  (gitignored)

Tests

npm test     # 76 tests, offline, against a throwaway CINEMA_ROOT (your data/ is never touched)

Covers the designer (valid, deterministic SVG; librsvg render when installed), stock clients against a mocked fetch (no key β†’ no request), screenplay quality rules, timeline/editorial rules, music/MIDI/SFX checks (loudness, clipping, structure), the MCP tool surface, and an offline end-to-end run that renders a real MP4 when ffmpeg or Remotion is present (skips cleanly otherwise). OMNICINEMA_TEST_REMOTION=1 npm test exercises Remotion instead of ffmpeg in that test.

Known limits

  • Offline photos are placeholders; offline video is an animatic, not footage.

  • Offline voices are robotic; offline music is synthesized (no sampled instruments, no vocals).

  • Logo/UI text depends on installed fonts; there is no font embedding or outlining.

  • The screenplay engine is template-based (deterministic). ANTHROPIC_API_KEY adds an optional prose rewrite.

  • Generative providers (Replicate/fal/HF) and stock APIs were unit-tested against mocked responses; they were not exercised against the live services in this release.

  • Remotion needs its headless Chrome download on first render; if Remotion fails, the pipeline falls back to ffmpeg.

Remotion licensing: free for individuals and small teams; a company license applies above a threshold β€” see https://remotion.dev/license.

License

MIT. Downloaded/generated assets keep their own licenses (see each project's attributions.txt). Please keep the scope boundary intact: official APIs + user-owned keys only; no scraping, token reuse, or auto-integration of untrusted code.

Available Tools

15 tools
approve_suggestionCatalogue a Reviewed SuggestionA

Use only after the user approves a discovered candidate. Adds it to tools-registry.json as DISABLED and unimplemented (a human must write an adapter and enable it). No network. Requires approve:true; otherwise does nothing.

Inputs: suggestionId (required), approve.

check_limitsCheck Free-Tier UsageA

Use before a generative run or when the user asks about remaining quota. Reports per-provider usage vs the budget guard's daily/weekly/monthly limits from data/usage-limits.json. Offline.

Inputs: provider.

compile_montageCompile / Re-render a Video ProjectA

Use after run_cinema_pipeline in interactive_montage mode, or to re-cut any project: rebuilds the timeline from the project folder (honoring an optional montage-order.json and any clip files you replaced), validates it (no gaps, no missing files) and renders the MP4. Offline; no network. Returns the MP4 path, validation warnings and next steps.

Inputs: projectId (required), render.

consult_personasPreview the Creative Brief (no generation)A

Use before generating to show/tune the strategy. Runs the persona consultation (Director of Photography, Graphic Designer, Voice Director, Music Producer) for an asset kind and returns the compiled brief: positive/negative prompt, technical params (palette, lens, BPM/key/structure, pacing) and the debate transcript. Instant, offline, writes nothing.

Inputs: subject (required), assetKind (required), style, aspectRatio.

discover_providersDiscover New Providers (review-only)A

Use when the user asks to find new video/model tools. Searches the public Hugging Face Hub and GitHub Search APIs (network, no key needed; GITHUB_TOKEN optional) and QUEUES candidates in data/review-queue.json. Never installs, enables or runs anything. Returns the top candidates and the queue size.

Inputs: query (required).

generate_imageDesign an Image (logo, vector art, UI mockup, photo)A

Use for logos, illustrations, app/web mockups, photos and textures.

  • logo / vector-art / ui-mockup: designed OFFLINE as clean SVG (plus a PNG export when rsvg-convert or ffmpeg is installed). Logos come with -reversed (dark backgrounds) and -icon variants. Free, instant, no network.

  • cinematic-photo / texture: need an image API. Without generative:true you get a clearly LABELLED placeholder, not a photo. generative:true calls Replicate/Hugging Face with your key (uses quota; budget-guarded β†’ returns a halt with a cost breakdown; retry with approveOverBudget:true only if the user agrees). Style words steer the result: palette ('vibrant', 'warm', 'earth', 'mono'), logo layout ('monogram', 'wordmark', 'horizontal', 'emblem'), type voice ('luxury', 'tech', 'playful'), 'sharp' corners. Returns file paths, size, license.

Inputs: subject (required), assetKind (required), style, generative, +2 more.

generate_sfxCreate a Sound EffectA

Use for a sound effect or ambience. Offline by default: procedural synthesis matched to the request (whoosh, rain, thunder, wind, ocean, impact, riser, click, ding, beep, fire, footsteps, heartbeat). generative:true searches Freesound with your FREESOUND_API_KEY (network, CC-licensed results, budget-guarded). Returns the file path, exact duration and license.

Inputs: subject (required), style, generative, approveOverBudget.

generate_soundtrackCompose a Soundtrack / BeatA

Use for background music or a beat in a genre: hip-hop, trap/rap, cinematic orchestral, rock, lo-fi, electronic, ambient. Offline by default: the Music Producer plans tempo/key/structure/instruments and the engine composes and synthesizes a stereo WAV (voice-led chords, bass, drums, a melody, section dynamics, mastered to about -14 LUFS) plus an editable multi-track MIDI. It is a synthesized demo, not a studio recording. generative:true uses your MusicGen model on Replicate/HF (quota, budget-guarded). Returns WAV + MIDI paths, exact duration, and the arrangement.

Inputs: subject (required), style, generative, durationSeconds, +1 more.

generate_voiceoverGenerate Voiceover / NarrationA

Use to turn a script into spoken audio (WAV). Offline by default via the system TTS engine (macOS 'say', pico2wave, ffmpeg's flite, or espeak-ng): intelligible but synthetic-sounding, loudness-normalized to -16 LUFS. If no engine exists you get a timing placeholder TONE that is explicitly labelled NOT SPEECH. generative:true uses your Hugging Face TTS model (HF_TTS_MODEL; quota, budget-guarded) for a natural voice. Returns the WAV path and exact duration in ms.

Inputs: subject (required), style, script, generative, +1 more.

install_dependenciesInstall Local Dependencies (consent required)A

Use when rendering fails because ffmpeg, Blender or the Remotion toolchain is missing. With consent:false (default) it only detects the OS and returns the exact commands it WOULD run β€” nothing is installed. Only call with consent:true after the user explicitly agrees; it then runs the package manager (may need sudo) and npm (network).

Inputs: consent, targets.

ipc_startStart Local REST APIA

Use when another local program needs to request assets from this engine over HTTP. Starts a server bound to 127.0.0.1 with a bearer token (stored in data/ipc-token.txt, mode 0600). Returns the URL and token. Stop it with ipc_stop.

Inputs: port.

ipc_statusLocal REST API StatusB

Use to check whether the local REST API is running and where. Offline.

Inputs: no named parameters.

ipc_stopStop Local REST APIA

Use to shut down the local REST API started by ipc_start.

Inputs: no named parameters.

list_providersList Providers & What Is ConfiguredA

Use to answer 'what can this server do with my keys?'. Lists every catalogued provider (stock, generative video/image, audio) with whether its key/model env vars are set. Offline; reads tools-registry.json and env only.

Inputs: no named parameters.

run_cinema_pipelineMake a Short Video (screenplay β†’ footage β†’ edit β†’ MP4)A

Use when the user wants a short video from a one-line idea. Writes a multi-scene screenplay with shot-to-shot continuity, fills each shot with stock footage (Pexels/Pixabay/Unsplash, only if their keys are set) or an offline storyboard frame, optionally adds narration (offline system TTS + captions) and a soundtrack fitted to the cut, edits a frame-accurate timeline (hard cuts in a scene, dissolves between scenes) and renders an MP4 with Remotion or ffmpeg. TIP: call with dry_run:true first β€” it returns the screenplay, shot list, provider choice and a cost/network estimate instantly without writing files, so you can show the user before producing. Network/money: stock APIs are used automatically when keys exist (free; set stock:false to stay offline). generative:true calls paid-or-quota video APIs (budget-guarded; approveOverBudget:true to exceed). With no keys everything runs offline. Returns: projectId, rendered MP4 path (if rendered), screenplay.md, timeline.json, attributions, warnings, next steps. interactive_montage pauses before the edit so a human can reorder/replace clips, then compile_montage finishes.

Inputs: prompt (required), fps, stock, style, +16 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (IPC trio, generation tools per asset kind, pipeline vs montage). The provider-management cluster (list_providers, discover_providers, check_limits, approve_suggestion) overlaps slightly, but descriptions differentiate 'what's available', 'find new', 'approve', and 'quota' well enough. generate_image bundles several sub-modes (logo/vector/ui-mockup vs cinematic-photo/texture) but is still a single coherent generation tool.

    Naming Consistency5/5

    All 15 tools use consistent snake_case with a verb_noun or verb_noun_noun pattern (generate_image, run_cinema_pipeline, ipc_start). The ipc_ prefix trio is a clean, predictable convention. No mixed camelCase or style deviations.

    Tool Count5/5

    15 tools sit at the top of the healthy 3-15 range and each earns its place: distinct asset generators (image/voice/soundtrack/sfx), a project pipeline, dependency install, provider registry management, and an IPC lifecycle. Nothing feels padded or redundant.

    Completeness4/5

    Covers image, voiceover, music, SFX generation, a full pipeline, provider discovery/approval, quota checks, and IPC serving. Minor gaps: no standalone create/list/delete project tools despite projectId being central, and no explicit generate_video tool although the pipeline references generative video APIs β€” agents can partly work around via run_cinema_pipeline and compile_montage.

    Related MCP Connectors

    Related MCP Servers