@vibeframe/mcp-server

The MCP (Model Context Protocol) server for VibeFrame. This package is only the MCP adapter — it exposes VibeFrame's operations as typed MCP tools so an MCP-capable host can call them by natural language.

Confirmed MCP hosts today: Claude Desktop, Cursor, OpenCode, and Claude Code (Claude Code can drive vibe natively via shell + AGENTS.md; the claude mcp add route below adds the typed-tool option for users who prefer it). For non-MCP hosts (Codex, Aider, Gemini CLI, anything else that shells out to bash), use @vibeframe/cli directly — same operations.

Just want a CLI? Use @vibeframe/cli instead — same operations, invoked directly in your shell as vibe <command>. This package and the CLI wrap the same underlying engine; pick whichever fits your workflow. Many users install both.

| Surface | Package | How you call it | |---------|---------|-----------------| | MCP host (Claude Desktop / Cursor / OpenCode / Claude Code) | @vibeframe/mcp-server (this) | host calls tool by name, for example mcp__vibeframe__build({...}) | | Shell / scripts (any agent host: Codex / Aider / Gemini CLI / etc.) | @vibeframe/cli | vibe init my-video && vibe build my-video && vibe render my-video | | Optional standalone agent REPL | @vibeframe/cli (vibe agent) | natural language -> CLI calls when you do not already use Claude Code/Codex/Cursor/etc. |

The tool list below is what the MCP host sees. The same operations exist as vibe <verb> <noun> subcommands in the CLI — see vibe --help.

Quick Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vibeframe": {
      "command": "npx",
      "args": ["-y", "@vibeframe/mcp-server"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "vibeframe": {
      "command": "npx",
      "args": ["-y", "@vibeframe/mcp-server"]
    }
  }
}

OpenCode

Add to .opencode/mcp.json (or your global config per opencode.ai/docs/config):

{
  "mcpServers": {
    "vibeframe": {
      "command": "npx",
      "args": ["-y", "@vibeframe/mcp-server"]
    }
  }
}

Claude Code

Claude Code drives vibe natively via shell + the scaffolded AGENTS.md / CLAUDE.md — MCP isn't required. If you'd like the typed-tool surface anyway:

claude mcp add vibeframe -- npx -y @vibeframe/mcp-server

What You Can Do

Once connected, your MCP host can resolve prompts like these into typed tool calls:

"Scaffold a 12-second Swiss-Pulse promo project, three beats, and render it" → init + 3× scene_add + render

"Generate a cinematic backdrop image, animate it for 5 seconds, add narration" → generate_image + generate_video + generate_speech

"Remove silent segments and add captions to my interview" → edit_silence_cut + edit_caption

Available Tools

Tool names are MCP-side. Your host typically prefixes them (e.g. Claude shows them as mcp__vibeframe__init). Each one wraps the same engine call as the matching vibe CLI subcommand.

Project flow (top-level)

| Tool | Description | |------|-------------| | init | Scaffold a video project with STORYBOARD.md + DESIGN.md | | build | Build a storyboard project: narration TTS, image assets, scene HTML composition | | render | Deterministic Hyperframes render → MP4/WebM/MOV |

Scene authoring (lower-level)

| Tool | Description | |------|-------------| | scene_list_styles | List the 8 vendored visual identities (Swiss Pulse, Data Drift, …) or fetch one | | scene_add | Append a beat (narration + backdrop + composed HTML) | | scene_install_skill | Install the Hyperframes skill bundle into a scene project | | scene_lint | Validate composition HTML against the visual identity | | scene_compose_prompts | Emit the per-beat compose plan without making an LLM call |

Generation (13)

| Tool | Description | Providers | |------|-------------|-----------| | generate_image | Text-to-image | OpenAI, Google, Stability | | generate_background | Cinematic backdrop image (video-tuned prompt) | OpenAI | | generate_video | Text/image-to-video (long-running) | Seedance via fal.ai, Grok, Kling, Runway, Google Veo | | generate_video_status / _cancel / _extend | Manage long-running video jobs | (provider-specific) | | generate_motion | Generate standalone designed motion graphics | Claude or Gemini + Remotion | | generate_speech | Text-to-speech | ElevenLabs | | generate_music | AI background music | Suno, ElevenLabs, Replicate MusicGen | | generate_music_status | Poll Replicate music task | Replicate | | generate_sound_effect | SFX from prompt | ElevenLabs | | generate_thumbnail | AI thumbnail composition | OpenAI, Google | | generate_storyboard | Multi-beat storyboard frames | OpenAI, Google |

Editing (16)

| Tool | Description | |------|-------------| | edit_silence_cut | Remove silent segments (FFmpeg or Gemini) | | edit_jump_cut | Remove filler words (Whisper) | | edit_caption / edit_animated_caption | Burn styled / animated captions | | edit_text_overlay | Simple static text burn-in | | edit_motion_overlay | Designed animated overlays or user-provided Lottie overlays | | edit_fade | Fade in/out | | edit_grade | Color grading | | edit_speed_ramp | Variable-speed segments | | edit_reframe | Aspect-ratio reframe (e.g. 16:9 → 9:16) | | edit_interpolate | Frame interpolation / slow-mo | | edit_upscale | AI upscaling | | edit_image | Image editing (gpt-image-2, Gemini) | | edit_noise_reduce | Audio/video denoise | | edit_translate_srt | Translate SRT subtitles | | edit_fill_gaps | Detect & fill missing video segments via TTS narration timing (Plan G — Phase 4) |

Audio (5)

| Tool | Description | |------|-------------| | audio_dub | AI voice dubbing (ElevenLabs) | | audio_clone_voice | Voice clone from sample | | audio_isolate | Vocal / background isolation | | audio_duck | Auto-duck BGM under speech | | audio_transcribe | Transcript with word-level timing (Whisper) |

Detection (3)

| Tool | Description | |------|-------------| | detect_silence | Find silent segments | | detect_scenes | Find shot boundaries | | detect_beats | Find music beats |

Inspection (4)

| Tool | Description | |------|-------------| | inspect_media | Unified image / video / YouTube analysis (Gemini) | | inspect_video | Temporal video understanding (Gemini) | | inspect_review | AI video review + auto-fix suggestions | | inspect_suggest | Natural-language project edit suggestions (Gemini); optional auto-apply |

Timeline (10)

| Tool | Description | |------|-------------| | timeline_create / timeline_info | Create or inspect low-level timeline JSON state | | timeline_add_source | Import media (video/audio/image) | | timeline_add_clip / _split_clip / _trim_clip | Build & shape clips | | timeline_move_clip / _duplicate_clip / _delete_clip | Arrange clips | | timeline_add_track | Add video/audio track | | timeline_add_effect | Apply effect (fade, blur, …) | | timeline_list | List all project contents |

Compatibility & Export

| Tool | Description | |------|-------------| | project_create / project_info | Deprecated compatibility aliases for timeline JSON state | | export_video | Export timeline JSON to MP4/WebM/MOV via FFmpeg |

Remix & pipelines (4)

| Tool | Description | |------|-------------| | run | Execute a multi-stage YAML pipeline (vibe run pipeline.yaml) | | remix_highlights | Long-form → highlight clips | | remix_auto_shorts | Long-form → vertical shorts | | remix_regenerate_scene | Re-render a single scene against an existing storyboard.{yaml,json} |

Guides (1)

| Tool | Description | |------|-------------| | guide | Cross-host guides for motion, scene, pipeline, and architecture workflows |

CLI ↔ MCP sync: packages/mcp-server/src/tools/cli-sync.test.ts is a vitest hook that fails CI when a CLI subcommand is added/removed/renamed without the matching MCP change. Open the test file to see the live mapping table — null rows mark CLI-only commands (e.g. vibe audio list-voices, vibe timeline set) that are intentionally not exposed via MCP.

Resources

| URI | Description | |-----|-------------| | vibe://project/current | Full project state | | vibe://project/clips | All clips | | vibe://project/sources | Media sources | | vibe://project/tracks | Track list | | vibe://project/settings | Project settings |

Prompts

| Prompt | Description | |--------|-------------| | edit_video | Natural-language editing instructions | | create_montage | Montage with automatic pacing | | add_transitions | Add transitions between clips | | color_grade | Apply color grading | | generate_subtitles | Subtitles via AI transcription | | create_shorts | Short-form from longer video | | sync_to_music | Cut to music beats |

Environment Variables

API keys are read from the host's environment (~/.zshrc, MCP config env block, etc.). All optional — only set the ones whose providers you use.

| Variable | Used by | |----------|---------| | OPENAI_API_KEY | gpt-image-2, Whisper, GPT | | ANTHROPIC_API_KEY | Claude (translate-srt, highlights, build compose pipeline) | | GOOGLE_API_KEY | Gemini (analyze, review, silence-cut, narrate) | | ELEVENLABS_API_KEY | TTS, voice-clone, dubbing, SFX | | XAI_API_KEY | Grok | | FAL_API_KEY | Seedance image-to-video | | RUNWAY_API_SECRET | Runway video | | KLING_API_KEY | Kling video | | IMGBB_API_KEY | Default temporary image host for Seedance/Kling image-to-video | | VIBE_UPLOAD_PROVIDER | imgbb (default) or s3 for temporary image uploads | | VIBE_UPLOAD_S3_BUCKET | S3 bucket when VIBE_UPLOAD_PROVIDER=s3 | | VIBE_UPLOAD_S3_PREFIX | Optional S3 key prefix for temporary image uploads | | VIBE_UPLOAD_TTL_SECONDS | Optional TTL hint for temporary upload URLs | | AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION | S3 upload host credentials | | VIBE_PROJECT_PATH | Default timeline JSON path for resources |

Requirements

• Node.js 20+
• FFmpeg on PATH (export, editing, pipelines)

License

MIT