PixelMotion MCP: Advanced AI-Powered SaaS Motion Graphics Engine

PixelMotion MCP is a production-grade Model Context Protocol (MCP) server, 3D motion graphics engine, and AI video director for crafting cinematic SaaS product films and interactive tutorials.

Unlike ordinary video generators that merely zoom into static screenshots with basic cursor pointers, PixelMotion treats your genuine user interface as a living, dimensional visual source. It orchestrates controlled 3D panel separations, camera dollies, spatial callouts, and seamless transitions into pixel-faithful 2D walkthroughs with beat-locked rhythm.

Key Pillars & Architectural Separation

PixelMotion separates production concerns into five modular layers:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MCP CLIENTS & WORKSPACES                          │
│     Claude Desktop  •  Cursor IDE  •  Zed  •  Companion Web Studio          │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ JSON-RPC 2.0 (stdio / SSE)
┌──────────────────────────────────────▼──────────────────────────────────────┐
│                            PIXELMOTION FASTMCP SERVER                       │
│  24 Production Tools: Reference, Reconstruction, Motion, Audio, Render, QA  │
└──────┬───────────────────────┬───────────────────────┬──────────────────────┘
       │                       │                       │
┌──────▼──────────────┐ ┌──────▼──────────────┐ ┌──────▼──────────────────────┐
│  AI MOTION DIRECTOR │ │ 3D MOTION ENGINE    │ │ UI FIDELITY ENGINE          │
│  • Narrative Beats  │ │ • Spatial UI Panels │ │ • 4-Tier Reconstruction     │
│  • Intent Reasoning │ │ • 3D Callouts/Lines │ │ • Locked Reference Layer    │
│  • Camera & Cursors │ │ • Transitions (6)   │ │ • Semantic Region Crops     │
└──────┬──────────────┘ └──────┬──────────────┘ └──────┬──────────────────────┘
       │                       │                       │
┌──────▼───────────────────────▼───────────────────────▼──────────────────────┐
│                         DUAL RENDERING & QA PIPELINE                        │
│   Remotion Components  •  Hyperframes Adapter  •  Headless Chromium Frame   │
│   Capturer  •  FFmpeg H.264 Encoder  •  Automated Visual QA Validation      │
└─────────────────────────────────────────────────────────────────────────────┘

1. Model Context Protocol (FastMCP) Core

Exposes 24 real tools over standard JSON-RPC 2.0 (stdio and SSE). Compatible with Claude Desktop, Cursor, Zed, or automated agents.

2. UI Fidelity & 4-Tier Reconstruction Priority

Strictly preserves interface identity without synthetic redesigns:

1. Tier 1 - Existing Source Code: When repository components are available.

2. Tier 2 - DOM / HTML / CSS Reconstruction: Clean, structured semantic layout.

3. Tier 3 - Cropped Original Assets: High-resolution extraction for complex charts, WebGL canvases, and proprietary widgets.

4. Tier 4 - Locked Reference Layer: Pristine base layer ensuring 100% pixel fidelity.

3. Dedicated 3D Motion Graphics Engine

• Spatial UI Compositions: Elevates dashboard cards into spatial Z-depth with dynamic soft contact shadows.

• 3D Feature Callouts: Connects dimensional highlight cards with curved animated SVG connectors and glowing focus frames.

• Camera Choreography: Deterministic dolly, orbit, spatial tracking, and match-cut transitions.

• Advanced Transitions: Spatial panel separation, camera-through-dashboard, perspective-to-flat collapse, 3D card rotation, and layered assembly.

4. AI Motion Director

Analyzes product geometry, narrative beat, and musical rhythm to generate a validated, multi-act production plan. Distinguishes between:

• Interface demonstration vs. Feature explanation

• Cinematic product opener vs. Closing call-to-action

• Data visualization vs. 3D spatial presentation

5. Dual Beat & Rhythm Engine

Built-in SciPy onset spectral flux detector and Librosa integration. Automatically detects tempo (BPM), classifies kick vs. snare onsets, and snaps scene cuts to 2-bar or 4-bar phrases.

6. Automated Visual QA Suite

Inspects output for:

• Interface pixel fidelity (MSE / PSNR diff)

• Crop boundary alignment and missing assets

• Typography legibility (12px body floor)

• Cursor targeting accuracy (verifies clicks hit actual element bounds)

• Container stream integrity (valid H.264 / AAC stream validation)

Related MCP server: uploop-vided MCP Server

16 Scene Composition Library

FastMCP Tools Reference

Reference Management

• reference.import(project_id, file_path): Ingests screenshot or video frame into project.

• reference.analyze(file_path): Extracts dimensions, dark/light mode, brightness, and dominant hex palette.

• reference.detect_regions(image_path): Uses OpenCV contour segmentation to locate cards, charts, and tables.

• reference.extract_asset(image_path, x, y, width, height, output_path): Crops exact high-resolution subpanel.

• reference.compare(ref_image_path, comp_image_path): Computes MSE, PSNR, and discrepancy bounding boxes.

UI Reconstruction

• ui.reconstruct(project_id, reference_id, image_path): Builds locked reference layer and spatial panel manifest.

• ui.validate(project_id, reference_id): Verifies all crops exist and match declared dimensions.

• ui.capture_state(target_url_or_image, output_path, is_live_url): Uses Headless Chromium to capture real state or synthesizes verified state variations.

Motion Direction

• motion.generate_plan(project_id, product_name, feature_focus, duration_seconds, bpm): Directs multi-act production plan.

• motion.generate_camera_path(motion_type, duration_frames, target_bbox): Synthesizes camera keyframe trajectory.

• motion.generate_cursor_path(start_x, start_y, target_x, target_y, start_frame, reach_frame): Generates tip-anchored cursor path with whip easing.

• motion.generate_3d_composition(panel_regions, elevation_step): Computes Z-depths and soft drop shadows.

• motion.validate(project_id): Checks scene timing, keyframe monotonicity, and typing budgets.

Scene & Timeline Management

• scene.create(project_id, scene_data): Adds a new scene to the timeline.

• scene.update(project_id, scene_id, updates): Updates an existing scene.

• scene.preview(project_id, scene_id): Compiles standalone preview HTML.

• scene.validate(scene_data): Validates scene boundaries and frame constraints.

Audio & Beat Sync

• audio.analyze_beats(audio_file_path, fps): Detects BPM, kick frames, snare frames, and 2-bar boundaries.

• audio.align_events(events, beats_data, max_nudge): Nudges in-scene events onto musical beats.

Rendering & Quality Assurance

• render.preview(project_id, scene_id): Renders fast 960x540 preview MP4.

• render.final(project_id, scene_id, audio_path): Renders 1080p master MP4 with audio muxing.

• render.status(job_id): Returns realtime render progress.

• render.cancel(job_id): Cancels an active rendering job.

Export Management

• export.video(input_mp4, output_path, preset): Exports with hd_1080p, 4k_master, social_9_16, or web_optimized.

• export.project(project_id, output_zip_path): Packages editable project archive into ZIP.

• export.assets(project_id, output_zip_path): Exports extracted UI components asset pack.

Installation & Setup

Prerequisites

• Python 3.10+

• Node.js 18+

• Chromium (or Google Chrome)

• FFmpeg 5.x+

git clone https://github.com/your-username/pixelmotion-mcp.git
cd pixelmotion-mcp
pip install -r requirements.txt

Running FastMCP Server

Stdio Mode (for Claude Desktop & Cursor)

python3 pixelmotion/server/mcp_server.py

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pixelmotion": {
      "command": "python3",
      "args": ["-m", "pixelmotion.server.mcp_server"]
    }
  }
}

HTTP / REST & Companion Web Studio Mode

python3 -c "from pixelmotion.server.fastmcp_compat import FastMCP; from pixelmotion.server.mcp_server import mcp; mcp.run(transport='http', port=8000)"

Open http://localhost:8000/companion/index.html to access the companion workspace.

End-to-End Acceptance Verification

The repository includes a comprehensive end-to-end acceptance test modeling a flagship Trading Journal Product Film:

python3 pixelmotion/tests/test_e2e_trading_journal.py

Test Results:

• Reference Ingestion: Analyzed 1920x1080 screenshot, dark mode, hex palette #22758B, #3EBDF6, #161C2A.

• Region Segmentation: Detected 10 semantic UI zones (Equity chart, KPI metrics, Trade executions table).

• UI Reconstruction: 100.0% fidelity score with locked reference layer.

• Beat Detection: 117.5 BPM, 35 kicks, 24 snares, 2-bar scene intervals.

• Motion Direction: 6-scene structured plan (900 frames / 30.0s).

• 3D Feature Spotlight (Act 3): Elevated performance card with 3D callout badge (+18.4% Alpha).

• Real Walkthrough (Act 4): Perspective collapsed to flat plane, whip-eased cursor clicked + Log Trade button.

• Render Output: 1080p MP4 rendered and audio-muxed via FFmpeg.

• Visual QA Scorecard: PASS (98.0% fidelity score across all 7 checks).

• Export: Saved playable master video and editable ZIP bundle.

Attribution & License

This project forks and significantly extends the foundational Remotion templates and scripts created by Noam Dorr under the MIT License.

PixelMotion MCP extensions copyright (c) 2026. Distributed under the MIT License. See LICENSE for details.

Additional Remotion motion templates

Three independently authored templates are included in remotion_templates/:

• AnimatedGradientText.tsx for a deterministic text-gradient sweep.

• DrawPath.tsx for SVG path drawing with a traveling endpoint marker.

• SpotlightCard.tsx for a subtle product-feature card reveal.

They use Remotion frame hooks and React, and can be imported into a composition after copying the files into your Remotion project's source tree. For example: import { SpotlightCard } from "./SpotlightCard";. See UPSTREAM_NOTICES.md for the upstream license review and provenance notes; Remotion itself is under a custom license, not MIT.

Railway-hosted remote MCP (Claude)

This repo includes a Dockerfile and railway.toml for a Railway deployment. The ASGI app exposes stateless MCP Streamable HTTP at /mcp and a health check at /health. For a Railway deployment, configure PIXELMOTION_API_TOKEN as a Railway secret variable before starting: protected MCP/API calls require Authorization: Bearer <token>. Full deployment and Claude connector steps are in RAILWAY_CLAUDE_SETUP.md. Review Railway usage pricing before deployment.