clipwright-text

MCP tool for annotating an OTIO timeline with text overlay markers. Text is not rendered here — clipwright-render reads the markers and applies drawtext filters when producing the output video.

Overview

clipwright-text is part of the clipwright suite. It is designed for AI agents, not humans — there is no GUI or interactive CLI. All interaction is via the MCP (Model Context Protocol) stdio transport.

Available Tools

How It Works

1. AI calls clipwright_add_text(timeline, output, options) once per text overlay.
2. The tool appends a text_overlay marker (name text_0, text_1, …) to the first video track of the timeline and writes a new .otio file to output.
3. The input timeline is never modified (non-destructive).
4. Repeated calls with identical options are idempotent — the second call returns applied=0 with a warning instead of duplicating the marker.
5. After annotating, pass the output OTIO to clipwright-render which converts the markers into drawtext ffmpeg filters and bakes the text into the video.

MCP Client Registration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "clipwright-text": {
      "command": "clipwright-text",
      "args": []
    }
  }
}

If clipwright-text is not on PATH, use the full path to the script or the Python interpreter:

{
  "mcpServers": {
    "clipwright-text": {
      "command": "/path/to/.venv/bin/clipwright-text",
      "args": []
    }
  }
}

clipwright_add_text Reference

Parameters

AddTextOptions Fields

Return Value

{
  "ok": true,
  "summary": "Added text overlay \"Hello\" at 1.0s for 3.0s. Timeline now has 1 text overlay(s). Output: out.otio.",
  "data": {
    "applied": 1,
    "overlay_count": 1,
    "start_sec": 1.0,
    "duration_sec": 3.0
  },
  "artifacts": [
    { "role": "timeline", "path": "/abs/path/out.otio", "format": "otio" }
  ],
  "warnings": []
}

On error:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "...",
    "hint": "..."
  }
}

Requirements

• Python >= 3.11
• opentimelineio >= 0.18
• mcp >= 1.27.2
• clipwright >= 0.3.0 (core library)

License

MIT