{"id":50157497,"url":"https://github.com/KyaniteLabs/mcp-video","last_synced_at":"2026-06-03T16:00:46.924Z","repository":{"id":345868071,"uuid":"1187652783","full_name":"KyaniteLabs/mcp-video","owner":"KyaniteLabs","description":"Guardrailed video editing MCP server for AI agents. FFmpeg, Hyperframes, repurposing tools, Python client, and CLI. Local, fast, free.","archived":false,"fork":false,"pushed_at":"2026-06-03T02:41:56.000Z","size":12394,"stargazers_count":29,"open_issues_count":13,"forks_count":8,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-03T04:23:46.616Z","etag":null,"topics":["agent-tools","ai-agents","ai-video","claude","claude-code","cli","cursor","ffmpeg","hyperframes","mcp","mcp-server","mcp-tools","media-automation","model-context-protocol","python","python-library","subtitles","video","video-automation","video-editing"],"latest_commit_sha":null,"homepage":"https://kyanitelabs.github.io/mcp-video/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KyaniteLabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["simongonzalezdc"],"ko_fi":"kyanitelabs"}},"created_at":"2026-03-21T01:27:25.000Z","updated_at":"2026-06-03T02:42:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KyaniteLabs/mcp-video","commit_stats":null,"previous_names":["pastorsimon1798/agentcut","kyanitelabs/mcp-video","pastorsimon1798/mcp-video"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/KyaniteLabs/mcp-video","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyaniteLabs%2Fmcp-video","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyaniteLabs%2Fmcp-video/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyaniteLabs%2Fmcp-video/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyaniteLabs%2Fmcp-video/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KyaniteLabs","download_url":"https://codeload.github.com/KyaniteLabs/mcp-video/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyaniteLabs%2Fmcp-video/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33872298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","ai-agents","ai-video","claude","claude-code","cli","cursor","ffmpeg","hyperframes","mcp","mcp-server","mcp-tools","media-automation","model-context-protocol","python","python-library","subtitles","video","video-automation","video-editing"],"created_at":"2026-05-24T13:00:32.266Z","updated_at":"2026-06-03T16:00:46.913Z","avatar_url":"https://github.com/KyaniteLabs.png","language":"Python","funding_links":["https://github.com/sponsors/simongonzalezdc","https://ko-fi.com/kyanitelabs"],"categories":["🖼️ Multimedia Processing","Video Processing Skills","📦 Other"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://kyanitelabs.tech\"\u003e\n    \u003cimg src=\"assets/mcp-video-hero.webp\" alt=\"mcp-video — guardrailed video editing MCP server for AI agents: FFmpeg, subtitles, audio, effects, and repurposing tools\" width=\"100%\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- mcp-name: io.github.KyaniteLabs/mcp-video --\u003e\n\n\u003ch1 align=\"center\"\u003emcp-video\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eGuardrailed video editing MCP server for AI agents.\u003c/strong\u003e\u003cbr\u003e\n  Structured tools for FFmpeg video editing, cinematic prompt planning, media analysis, subtitles, audio, effects, Hyperframes video creation, local repurposing packages, and preflight validation that helps prevent silent bad media output.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/mcp-video/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/mcp-video.svg\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/KyaniteLabs/mcp-video/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/KyaniteLabs/mcp-video/.github/workflows/ci.yml?branch=master\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MCP-119%20tools-orange.svg\" alt=\"119 MCP tools\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.11%2B-blue.svg\" alt=\"Python 3.11+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"Apache 2.0\"\u003e\n  \u003ca href=\"https://registry.modelcontextprotocol.io/servers/io.github.KyaniteLabs/mcp-video\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP-Registry-blue.svg\" alt=\"MCP Registry\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#what-agents-can-do\"\u003eAgent Workflows\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#tool-surface\"\u003eTools\u003c/a\u003e \u0026bull;\n  \u003ca href=\"docs/TOOLS.md\"\u003eTool Reference\u003c/a\u003e \u0026bull;\n  \u003ca href=\"docs/AI_AGENT_DISCOVERY.md\"\u003eAI Discovery\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#agent-skill\"\u003eAgent Skill\u003c/a\u003e \u0026bull;\n  \u003ca href=\"llms.txt\"\u003ellms.txt\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://registry.modelcontextprotocol.io/servers/io.github.KyaniteLabs/mcp-video\"\u003eMCP Registry\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Public Discovery\n\n**mcp-video** is a free, open-source **Model Context Protocol (MCP) server**, Python library, and CLI that gives AI agents a real video-editing surface. It wraps FFmpeg, PUSHING CREATION-style planning, media analysis, quality checks, subtitles, audio generation, effects, Hyperframes 0.5 rendering, local repurposing packages, and guardrails for risky edit parameters behind structured tool schemas.\n\nBest-fit searches:\n\n- video editing MCP server\n- AI agent video editing\n- FFmpeg MCP tools\n- Claude Code video editing\n- Cursor MCP video tools\n- Python video editing library\n- subtitle automation\n- reels and shorts automation\n- agentic media pipeline\n- local AI video workflow\n- Hyperframes video creation\n- YouTube Shorts repurposing\n\n## Why It Exists\n\nAI agents can write FFmpeg commands, but they should not have to guess flags, parse brittle stderr, or silently publish broken media. mcp-video gives agents typed operations, inspectable tool metadata, structured results, preflight guardrails, and quality checkpoints so a video workflow can be automated and reviewed without turning into shell-command roulette.\n\nUse it when you want an AI assistant to:\n\n- trim, merge, resize, crop, rotate, transcode, or export video;\n- add text, subtitles, watermarks, overlays, filters, fades, effects, and transitions;\n- extract audio, normalize audio, synthesize audio, add generated audio, or create waveforms;\n- detect scenes, make thumbnails, generate storyboards, compare quality, and create release checkpoints;\n- scaffold cinematic projects, read STYLE_/NEG_ blocks, parse storyboard tables, and expand shot prompts;\n- create new Hyperframes projects, inspect rendered layouts, capture websites, generate local speech, remove backgrounds, and post-process the result with FFmpeg tools;\n- repurpose one source video into vertical, horizontal, and square local delivery packages with manifests and review artifacts;\n- drive repeatable media workflows from Claude Code, Cursor, Codex-style clients, scripts, or CI.\n\n## Installation\n\nPrerequisite: [FFmpeg](https://ffmpeg.org/) must be installed and available on `PATH`.\n\n```bash\n# macOS\nbrew install ffmpeg\n\n# Ubuntu/Debian\nsudo apt install ffmpeg\n```\n\nRun without a global install:\n\n```bash\nuvx --from mcp-video mcp-video doctor\n```\n\nOr install with pip:\n\n```bash\npip install mcp-video\nmcp-video doctor\n```\n\nHyperframes tools additionally need Node.js 22+ and a resolvable Hyperframes CLI. Install/pin Hyperframes in the active Node package layout, add `hyperframes` to `PATH`, or set `MCP_VIDEO_HYPERFRAMES_COMMAND`.\n\n## Quick Start\n\n### Claude Code\n\n```bash\nclaude mcp add mcp-video -- uvx --from mcp-video mcp-video\n```\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-video\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-video\", \"mcp-video\"]\n    }\n  }\n}\n```\n\n### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-video\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-video\", \"mcp-video\"]\n    }\n  }\n}\n```\n\nThen ask your agent:\n\n\u003e Trim this interview into a 45-second vertical clip, add burned captions, normalize the audio, make a thumbnail, and create a release checkpoint before export.\n\n## Agent Skill\n\nmcp-video includes a public agent skill at [`skills/mcp-video/SKILL.md`](skills/mcp-video/SKILL.md). Use `$mcp-video` in compatible agent hosts when you want the agent to choose between the MCP server, CLI, and Python client while preserving the inspect, edit, verify, and human-review workflow.\n\n## Python Client\n\n```python\nfrom mcp_video import Client\n\neditor = Client()\n\nclip = editor.trim(\"interview.mp4\", start=\"00:02:15\", duration=\"00:00:45\")\ncaption_file = \"captions.srt\"\neditor.ai_transcribe(clip.output_path, output_srt=caption_file)\ncaptioned = editor.subtitles(clip.output_path, subtitle_file=caption_file)\nvertical = editor.resize(captioned.output_path, aspect_ratio=\"9:16\")\ncheckpoint = editor.release_checkpoint(vertical.output_path)\n\nprint(checkpoint[\"thumbnail\"])\nprint(checkpoint[\"storyboard\"])\n```\n\n## CLI\n\n```bash\nmcp-video info interview.mp4\nmcp-video trim interview.mp4 -s 00:02:15 -d 45\nmcp-video video-ai-transcribe clip.mp4 --output captions.srt\nmcp-video subtitles clip.mp4 captions.srt\nmcp-video resize clip.mp4 --aspect-ratio 9:16\nmcp-video video-quality-check clip.mp4\nmcp-video repurpose clip.mp4 --platforms youtube-shorts instagram-reel tiktok\n```\n\n## What Agents Can Do\n\n| Workflow | Example prompt |\n| --- | --- |\n| Social clips | \"Turn this landscape recording into a captioned TikTok and YouTube Short.\" |\n| Podcast production | \"Find the strongest segment, trim it, normalize audio, add chapters, and export.\" |\n| Product demos | \"Create a short launch video from screenshots, title cards, and voiceover.\" |\n| Cinematic planning | \"Create a style pack and storyboard, then render shot prompts for generation.\" |\n| Quality review | \"Compare these two exports, make thumbnails, and flag visual or audio problems.\" |\n| Batch automation | \"Convert this folder of clips to web-ready MP4 with consistent loudness.\" |\n| Code-created video | \"Scaffold a Hyperframes composition, inspect it, render it, then add subtitles and a watermark.\" |\n| Local repurposing | \"Turn this master clip into Shorts, Reels, TikTok, and YouTube assets with thumbnails and a manifest.\" |\n\n## MCP Tools\n\nmcp-video currently registers **119 MCP tools**. The table below summarizes the documented core categories; `search_tools` lets agents discover the exact operation they need without loading every tool description into context.\n\n| Category | Count | Highlights |\n| --- | ---: | --- |\n| Core video editing | 32 | trim, merge, resize, crop, rotate, convert, overlays, subtitles, export, cleanup, templates, merge-compatibility guardrails |\n| Cinematic creation | 4 | project scaffold, style-pack parsing, storyboard parsing, shot prompt expansion |\n| AI-assisted media | 11 | transcription, scene detection, upscaling, stem separation, silence removal, color grading |\n| Hyperframes | 18 | init, preview, render, snapshots, inspect, catalog, website capture, local TTS, transcription, background removal, diagnostics, benchmark, post-process |\n| Repurposing | 2 | dry-run manifests, platform-ready variants, thumbnails, storyboards, release checkpoints |\n| Procedural audio | 7 | synthesize, compose, presets, effects, sequences, generated audio, spatial audio, mix-parameter guardrails |\n| Visual effects | 8 | vignette, glow, noise, scanlines, chromatic aberration, luma key, mask, shape mask, bounded filter parameters |\n| Transitions | 3 | glitch, morph, pixelate |\n| Layout and motion | 6 | grid, picture-in-picture, split-screen, animated text, counters, progress bars, auto-chapters, layout mismatch warnings |\n| Analysis | 8 | scene detection, thumbnail, preview, storyboard, quality compare, metadata, waveform, release checkpoint |\n| Image analysis | 3 | extract colors, generate palettes, analyze product images |\n| Discovery | 1 | `search_tools` |\n\n```python\nfrom mcp_video import Client\n\neditor = Client()\nmatches = editor.search_tools(\"subtitle\")\nprint(matches[\"tools\"])\n```\n\nFull reference: [docs/TOOLS.md](docs/TOOLS.md)\n\n## Agent-Safe Workflow\n\nFor autonomous agents, the intended path is inspect, edit, verify, then ask a human to review release artifacts:\n\n```python\nfrom mcp_video import Client\n\nclient = Client()\n\nprint(client.inspect(\"trim\"))\n\nresult = client.pipeline(\n    [\n        {\"op\": \"trim\", \"input\": \"source.mp4\", \"start\": \"00:01:00\", \"duration\": \"00:00:45\"},\n        {\"op\": \"add_text\", \"text\": \"Launch clip\", \"position\": \"top-center\"},\n        {\"op\": \"normalize_audio\"},\n        {\"op\": \"resize\", \"aspect_ratio\": \"9:16\"},\n        {\"op\": \"export\", \"quality\": \"high\"},\n        {\"op\": \"release_checkpoint\"},\n    ],\n    output_path=\"final-short.mp4\",\n)\n```\n\nSafety contract:\n\n- Media-producing calls return structured results with output paths.\n- High-risk edit paths now run preflight guardrails before FFmpeg execution: filter bounds, merge compatibility, audio mix volume/timing, overlay/watermark/chroma opacity and similarity, animated text timing/overflow, and grid/split-screen mismatch warnings.\n- Analysis and discovery calls return structured JSON reports.\n- Tool discovery is available through `search_tools()` and `Client.inspect()`.\n- Unexpected keyword errors are converted into actionable `MCPVideoError` guidance.\n- Do not publish agent-generated video without `video_quality_check`, `video_release_checkpoint`, and human visual/audio inspection.\n\n## Documentation\n\n- [Tool reference](docs/TOOLS.md)\n- [Python client reference](docs/PYTHON_CLIENT.md)\n- [CLI reference](docs/CLI_REFERENCE.md)\n- [AI agent discovery guide](docs/AI_AGENT_DISCOVERY.md)\n- [FAQ](docs/faq.md)\n- [llms.txt](llms.txt)\n\n## Testing\n\nDevelopment verification lives in [docs/TESTING.md](docs/TESTING.md). Keep public-surface, media workflow, and security checks current when changing tool behavior.\n\n## Development\n\n```bash\ngit clone https://github.com/KyaniteLabs/mcp-video.git\ncd mcp-video\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\npytest tests/ -v -m \"not slow and not hyperframes\"\n```\n\n## Community\n\n- [Contributing](CONTRIBUTING.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Governance](GOVERNANCE.md)\n- [Maintainers](MAINTAINERS.md)\n- [Security](SECURITY.md)\n- [Support](SUPPORT.md)\n- [Roadmap](ROADMAP.md)\n- [Changelog](CHANGELOG.md)\n- [GitHub Discussions](https://github.com/KyaniteLabs/mcp-video/discussions)\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n\nBuilt with [FFmpeg](https://ffmpeg.org/), [Hyperframes](https://hyperframes.io/), and the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n---\n\n## Part of KyaniteLabs\n\nMore from [KyaniteLabs](https://kyanitelabs.tech). Related projects:\n\n- **[Epoch](https://github.com/KyaniteLabs/Epoch)** — time-estimation MCP server (PERT) for AI agents\n- **[DialectOS](https://github.com/KyaniteLabs/DialectOS)** — Spanish dialect localization MCP server \u0026 CLI\n- **[checkyourself](https://github.com/KyaniteLabs/checkyourself)** — local-first production-readiness checks for AI-built code\n\n→ More at **[kyanitelabs.tech](https://kyanitelabs.tech)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKyaniteLabs%2Fmcp-video","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKyaniteLabs%2Fmcp-video","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKyaniteLabs%2Fmcp-video/lists"}