omnicinema-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@omnicinema-mcp Generate a 15-second ad with voiceover and background music."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π¬ 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 ( |
Voiceover | Real speech via | 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 |
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
flitevoice.rsvg-convert (
librsvg2-bin/brew install librsvg) β PNG export of every SVG.espeak-ng (Linux) β offline narration if neither
saynor 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 toolchainAll 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 haveVariable | Enables | Network / cost |
| Stock video/photos in | Free APIs; used automatically when set ( |
| Real SFX recordings ( | Free API |
| Photos, natural voice, MusicGen, video | Quota / paid, only with |
| Same, via Replicate | Paid, only with |
| Video via fal.ai | Paid, only with |
| Optional screenplay prose polish (1 call per run; | 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 |
| Turn an idea into a video. Start with | Stock APIs if keys set; |
| Finish an | None |
| Logo, vector art, UI mockup (offline SVG+PNG), photo/texture (API). | Only photo/texture with |
| Speak a script (offline TTS or HF TTS). | Only with |
| Compose music in a genre, optionally to a length ( | Only with |
| Sound effect / ambience. | Freesound with |
| Preview the compiled brief without generating. | None |
| See free-tier usage per provider. | None |
| See which providers are configured. | None |
| Preview ( | Installs only with consent |
| Queue candidate providers for review / catalogue one (added disabled). | Public catalog search |
| Local REST API for other tools (for a long-running service use | Localhost only |
Typical flow
run_cinema_pipeline { prompt, dry_run: true }β show the user the shot list and spend (usually "Nothing").run_cinema_pipeline { prompt, narration, soundtrack: true, musicStyle }β MP4 path + screenplay + timeline.Optional: edit
montage-order.jsonor 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.mdis 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_KEYadds 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 toolsapprove_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
Scored across 15 tools
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.
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.
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.
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
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Hosted MCP server for AI agents to post to LinkedIn profiles and X and upload to YouTube.
Hosted MCP server for live public-data APIs and Skills for AI agents.
AI video, image and audio generation with 140+ AI models from any MCP agent
Related MCP Servers
- AlicenseAqualityFmaintenanceProduction-grade MCP server for image and video understanding and generation across Gemini, OpenAI, and Grok.5114 PyPI4Apache 2.0
- AlicenseAqualityDmaintenanceMulti-provider media generation MCP server that generates images, videos, audio, and transcriptions from text prompts using OpenAI, xAI, Gemini, ElevenLabs, and BFL through a single unified interface.6169 npm2MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables local AI agents to generate images and videos through the OpenRouter API, manage a browsable media library, and track generation costs.11MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that lets AI agents generate images and videos, build websites, and produce designed PDFs with transparent model routing, cost tracking, and local artifact mirroring.127MIT