SceneWeaver MCP

A local MCP connector that turns an assistant's script into a narrated short video. Plan scenes, inspect a storyboard, choose media, preview a voice, then render to a requested duration. No LLM API key is required: your existing assistant supplies the narration and search terms.

SceneWeaver is an early release. Review the storyboard and asset credits before publishing a video. Visual relevance still benefits from a human's judgment.

Install locally

Requires Python 3.11 or newer and a supported 64-bit platform. Python 3.11 or 3.12 is recommended for the optional voice engine's native dependencies. Installation downloads Python packages; voice models are a separate explicit download.

Download and extract a release bundle from GitHub Releases, then install its wheel in a virtual environment:

The bundle also contains examples/install-windows.cmd and examples/install-posix.sh. Run the matching installer from a terminal to create a local environment and install the voice extra. Then run setup-voice explicitly as shown below. These scripts download packages; they do not download voice models. At the end, they detect supported client configuration folders and offer to connect one client. Press Enter to skip. Plain pip install never edits client settings.

# Windows PowerShell, from the extracted bundle directory
py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install "./sceneweaver_mcp-0.1.2-py3-none-any.whl[voice]"
.\.venv\Scripts\sceneweaver-mcp setup-voice
.\.venv\Scripts\sceneweaver-mcp doctor

# macOS / Linux, from the extracted bundle directory
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install './sceneweaver_mcp-0.1.2-py3-none-any.whl[voice]'
.venv/bin/sceneweaver-mcp setup-voice
.venv/bin/sceneweaver-mcp doctor

For a source checkout, replace the wheel path with '.[voice]'. With uv, run uv sync --extra voice, then uv run sceneweaver-mcp setup-voice. The voice extra installs Kokoro ONNX and its speech dependencies; setup-voice downloads approximately 355 MB of integrity-checked model and voice files. It never runs silently when the MCP server starts. Installing the core without [voice] still provides planning and media tools; local narration requires the extra and models.

FFmpeg is supplied through imageio-ffmpeg on supported platforms. Its executable and codec licensing are separate from this project's Apache license. See third-party notices before redistributing an environment.

Related MCP server: postward-creative-mcp

Connect an MCP client

Run sceneweaver-mcp connect for automatic detection and an opt-in setup prompt. It supports Codex shared configuration, Cursor, and Claude Desktop on Windows/macOS. It checks known configuration folders rather than scanning your computer. Choose one client; an existing configuration is backed up before SceneWeaver is added.

For a read-only check, run sceneweaver-mcp clients. To preview a specific change, run sceneweaver-mcp connect --client cursor --dry-run. To explicitly apply it, omit --dry-run. Client IDs are codex, cursor, and claude-desktop.

Restart the selected client and approve SceneWeaver there. Detection does not prove that a client is installed or enabled, and does not bypass its permissions. Only one server may own the default storage at a time; close other clients using it or configure separate SCENEWEAVER_HOME directories. See client setup for supported paths, backups, and manual setup limitations.

Use the absolute executable path from the environment you just installed. The server uses stdio and needs no localhost port. A generic client configuration is in examples/mcp.json; adapt it to your client's schema.

{
  "mcpServers": {
    "sceneweaver": {
      "command": "/absolute/path/to/.venv/bin/sceneweaver-mcp",
      "args": ["serve"]
    }
  }
}

On Windows, use C:\\absolute\\path\\.venv\\Scripts\\sceneweaver-mcp.exe. Run sceneweaver-mcp version to confirm the executable. Set SCENEWEAVER_HOME in the MCP process environment if you want to choose where state, media and results are stored; doctor reports the active location.

The optional launchers are examples/run-windows.cmd and examples/run-posix.sh. If your client needs an interpreter to launch a script, use cmd /d /c on Windows or sh on POSIX, with the absolute script path as arguments. The installed sceneweaver-mcp executable above is the simplest configuration. POSIX launchers can also be run as sh examples/run-posix.sh if executable permission was not preserved by ZIP extraction.

Make a video

Ask your connected assistant:

Make a 15-second video explaining how trees cool cities. Plan three scenes, find relevant footage from the available providers, and show the storyboard. Preview the narrator before rendering. Use quiet background music, concise captions and the selected scenes. Give me the video and its asset credits.

The workflow is: plan scenes → search and select media → review storyboard → preview narration → generate → check progress → retrieve results. You can replace a scene's selection before rendering and cancel an active job. Cached downloads reduce repeat requests, while provider cooldowns avoid repeatedly hitting a limited service. Uploaded/imported media must be yours to use.

The renderer fits measured narration to the requested duration within its allowed speed range; it fails with a useful message when the script needs rewriting rather than forcing an unnatural voice speed. Caption timing uses measured sentence boundaries. Phrase and word highlighting use estimated timing inside those sentences, rather than speech-recognition word alignment.

Branding supports a title, footer, six-digit hex color and an imported logo asset ID.

create_storyboard accepts scenes containing text, query, an optional asset_id and optional duration_seconds. Set durations for every scene or let the planner allocate them by word count. Set the total duration_seconds (1–120), aspect (9:16, 16:9 or 1:1), voice, music (ambient or none), music_volume (0–0.18), branding and caption_style (sentence, phrase or word). Available Kokoro voices are af_heart, af_bella, am_michael and bf_emma.

To import media, place a file in the managed inbox/ under the storage directory reported by doctor, then call import_media with its filename and rights metadata. Tools cannot import an arbitrary absolute path. Provider searches and downloads require allow_network=true; choose it only with the user's permission.

Voice previews return a WAV path and sceneweaver://voice/{preview_id} resource. Storyboard previews include an inline PNG contact sheet and can also be read from sceneweaver://storyboard/{storyboard_id}/preview. Playback and resource display depend on the connected MCP client's capabilities. Video results include the local MP4 path, its checksum, credits and a quality report.

Providers and integrations

Wikimedia Commons and Openverse provide image discovery; Pexels provides stock video discovery through the optional API-Anything bridge. Individual providers can be unavailable or rate-limited. Media credits travel with the job. A free website does not automatically grant permission for any use of its content.

Kokoro runs locally without an API key after setup. The generated ambient music bed contains no external song recording. Additional local voice service options are documented as research; an API-Anything speech connector is not included in this release.

See integration setup and provider options, privacy and security, and licensing.

Develop and package

python -m pip install -e '.[dev,voice]'
python -m unittest discover -s tests -v
python scripts/package_release.py
python -m pip_audit

The release script builds a wheel, source distribution, downloadable ZIP bundle and SHA-256 checksums in dist/. It packages code and documentation, never local jobs, cached downloads, voice models or credentials. Builds install dependencies from package indexes; the bundle is not an offline all-dependencies installer. CI covers Windows, macOS and Linux; a configured workflow is not a claim that remote CI has already passed for an unpublished commit.

Release verification on Windows: the local test suite passed, an actual stdio MCP job rendered an exact 15-second video with local Kokoro narration, and an actual API-Anything Commons search returned six assets. macOS/Linux checks are configured in CI but have not yet been executed for this release. These checks do not certify all provider availability, narration pronunciations or asset rights.

License

Original code: Apache-2.0, copyright SceneWeaver contributors. External components and downloaded assets keep their own licenses and required attributions. SceneWeaver is not endorsed by its media or voice providers.