Metadata-Version: 2.5
Name: video-generation-mcp
Version: 0.2.1
Summary: MCP server that makes narrated 'tech explained' reels (3D or 2D), image posts and infographics.
Project-URL: Homepage, https://github.com/SalindaHulangamuwa/video-generation-mcp
Project-URL: Issues, https://github.com/SalindaHulangamuwa/video-generation-mcp/issues
Project-URL: Changelog, https://github.com/SalindaHulangamuwa/video-generation-mcp/blob/main/CHANGELOG.md
Author-email: Salinda Hulangamuwa <salindahulangamuwa3@gmail.com>
Keywords: fastmcp,ffmpeg,gemini,mcp,model-context-protocol,reels,three.js,tts,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastmcp<5,>=4.1
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10
Requires-Dist: playwright==1.56.0
Requires-Dist: pocketsphinx>=5.1
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# video-generation-mcp

An MCP server that makes narrated "tech explained" reels for Facebook, Instagram and YouTube Shorts:
script → Gemini voice → line timings → **3D (three.js) or 2D** visuals → background render → music mix → final mp4.
It also makes white editorial image posts, step-by-step infographics, thumbnails, captions and other formats.

Built with [FastMCP](https://gofastmcp.com) for Claude Desktop, Claude Code and any MCP client.

## Tools (39)

| Area | Tools |
|---|---|
| Overview | `list_reels`, `reel_status`, `studio_doctor` |
| Reel + script | `create_reel`, `write_script`, `check_script`, `write_caption_file` |
| Voice | `generate_voice`, `speak_script`, `speak`, `import_voice` |
| Timing | `align_voice`, `set_line_times` |
| Code + assets | `list_files`, `read_file`, `write_file`, `add_asset`, `list_templates`, `save_as_template` |
| Look before rendering | `render_stills` (contact sheet image), `safe_zone_check` |
| Render | `start_render`, `render_status`, `cancel_render`, `finish_reel` |
| Music | `set_music` (calm, upbeat, tense, ambient, none), `import_music` |
| After rendering | `preview_video`, `check_audio`, `add_captions`, `make_thumbnail`, `export_formats`, `trim_or_speed`, `compress_video` |
| Image posts | `render_image_post`, `render_infographic` |
| Planning + cleanup | `log_topic`, `list_topics`, `clean_reel` |

A typical reel: `create_reel` → `write_script` → `check_script` → `generate_voice` → `align_voice` →
`write_file` (3d/world.js, 3d/shots.js) → `render_stills` → `safe_zone_check` → `start_render` → `render_status` →
`preview_video`.

## Install

Requirements: Python 3.10+, [uv](https://docs.astral.sh/uv/), ffmpeg (with libass for burned captions).

```bash
cp .env.example .env            # set BX_STUDIO_DIR and GEMINI_API_KEY
uv sync
uv run playwright install chromium
uv run video-generation-mcp doctor
```

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
"video-generation-mcp": {
  "command": "uv",
  "args": ["run", "--directory", "/path/to/studio-mcp", "video-generation-mcp"]
}
```

## Configuration

| Variable | Default | Meaning |
|---|---|---|
| `BX_STUDIO_DIR` | required | Studio folder with `reels/`, `posts/`, `templates/`, `topics.json` |
| `GEMINI_API_KEY` | — | Text-to-speech key (also read from `<studio>/.env`) |
| `BX_VOICE` / `BX_TTS_MODEL` | `Iapetus` / `gemini-2.5-flash-preview-tts` | Default voice and model |
| `BX_GL` | `auto` | `gpu` (macOS default), `swiftshader` (software) |
| `BX_FPS` / `BX_WORKERS` | `24` / `2` | Render frame rate and parallel browser workers |
| `BX_FOOTNOTE` | `Simulated · illustration` | Small footnote on 3D frames |
| `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT` | `stdio`, `127.0.0.1`, `8000` | Server transport |

Run `video-generation-mcp --read-only` to expose only the tools that don't write files.

## Docs

- [Architecture](docs/architecture.md)
- [Writing a 3D reel](docs/3d-reel-contract.md)
- [Mac setup and development](docs/setup-mac.md)

## Development

```bash
uv sync
uv run pytest              # 62 tests; browser/ffmpeg tests skip when those are missing
uv run ruff check src tests && uv run mypy
```
