---

Why

LLMs are good at writing SVG, but "make me an animation" usually produces something stiff and templated. text2animate fixes that two ways:

1. It bakes in motion-design best practices — layered scenes, natural easing, anticipation/overshoot, seamless loops, restrained palettes — and hands them to the model before it draws anything.
2. It closes the feedback loop. The result renders instantly in a local preview, and a chat box under the animation lets you say "make the goose have webbed feet and add parallax mountains" — the change applies live, through your own Claude Code session.

No API key, no separate billing — edits run on the model you're already using.

How it works

                    create_animation
   ┌──────────┐   ──────────────────►   ┌──────────────────┐   ──►  Preview UI
   │  Claude  │                          │  text2animate    │        (floating,
   │ (MCP host)│  ◄──────────────────    │  MCP server      │   ◄──   live over SSE)
   └──────────┘    await_edit_request    └──────────────────┘
        ▲          (long-poll for your         │  embeds best practices
        │           typed changes)             │  validates + stores SVG
        └─ apply_patch / apply_edit ───────────┘  serves the local UI

The model is the renderer's brain. Guided by the embedded best practices, it writes a self-contained <svg> with @keyframes/SMIL animation. The server validates it, stores it, and serves a preview. When you type a change, the server queues it and the in-session agent picks it up, edits the SVG, and the preview refreshes.

Install

Option A — Claude Code plugin (recommended)

No clone, no build. In Claude Code:

/plugin marketplace add tom-pettit/text2animate
/plugin install text2animate@tom-pettit

That registers the MCP server (it runs a prebuilt, dependency-free bundle), so just ask:

"Use text2animate to animate a goose waddling through the grass, playful style."

The preview opens automatically at http://127.0.0.1:4321. The CLI equivalent:

claude plugin marketplace add tom-pettit/text2animate
claude plugin install text2animate@tom-pettit

Option B — from source (for development)

git clone https://github.com/tom-pettit/text2animate.git
cd text2animate
npm install

npm install builds the server and auto-registers it in the surrounding workspace's .mcp.json (merging — it never clobbers other servers). Restart Claude Code to pick it up.

[!TIP] Registering somewhere specific, or not at all:

npm run register -- ~/.mcp.json   # a specific config file
npm run unregister                # remove the entry
T2A_NO_AUTO_REGISTER=1 npm install # skip auto-registration

Resolution order: explicit path → T2A_MCP_TARGET env → <repo-parent>/.mcp.json.

Styling the look

Tell it the aesthetic and the server feeds concrete art direction (palette, shape language, motion feel, typography) to the model. Use a preset or any freeform phrase:

"Animate a loading spinner, minimalistic but modern."

Built-in presets: minimal-modern, playful, neon-cyber, flat-corporate, hand-drawn, retro-80s. The chosen style is recorded and shown in the preview's properties panel.

Live editing (the chat box)

Under the animation is a ChatGPT-style box. Type a change and it round-trips through your Claude Code session:

1. The box queues your request on the server.
2. The agent's watch loop (await_edit_request) is long-polling — it unblocks with your text and the current SVG.
3. The agent applies the change; the preview updates live.

Fast iteration. Small tweaks (color, size, timing, text, easing) go through apply_patch — the agent sends a tiny find/replace instead of re-emitting the whole document, so a recolor is ~10 tokens rather than a full regeneration. Structural changes fall back to apply_edit. A bad patch is rejected wholesale (nothing changes) so the request stays open to retry.

To turn it on, tell Claude once: "watch the preview for edits" — it keeps calling await_edit_request. Pairs naturally with /loop, and /fast makes each turn snappier. The box shows a green dot when a watcher is connected, amber when it isn't.

Preview UI

A light, floating interface (no chrome docked to the edges):

• Artboard — the animation in a 16:9 frame, centered on a warm canvas.
• Animations panel (left) — everything created this session.
• Properties panel (right) — style, duration, loop, and Export SVG.
• Playback (bottom-right) — play/pause (Space) and restart (R); pausing freezes both CSS @keyframes and SMIL timelines.
• Chat dock (bottom) — the live-edit box plus the watcher status.

Tools, resources & prompts

Tool	Purpose
get_best_practices	The animation guidelines. Optional style adds concrete art direction.
list_styles	List the built-in style presets.
create_animation	Render a self-contained animated <svg> in the preview and open it.
list_animations	List animations created this session.
await_edit_request	Long-poll for a change typed into the preview's chat box.
apply_patch	Fast edit: apply small find/replace tweaks in place.
apply_edit	Apply a fully regenerated SVG in place.
open_preview	Ensure the preview server is running and open it.

Also exposed: an animation-best-practices resource and an animate prompt.

Configuration

Variable	Default	Meaning
TEXT2ANIMATE_PORT	4321	Preferred preview port (walks upward if taken).
T2A_MCP_TARGET	<repo-parent>/.mcp.json	Where register writes the MCP entry.
T2A_NO_AUTO_REGISTER	–	Set to skip auto-registration on npm install.

Development

npm run build      # compile TypeScript → dist/
npm run dev        # tsc --watch
npm run typecheck  # tsc --noEmit
npm test           # node:test suite (via tsx)
npm run serve      # run just the preview UI (no MCP stdio channel)

Stack: TypeScript + @modelcontextprotocol/sdk (stdio) for the MCP server, Express + Server-Sent Events for the preview. Animations are self-contained SVGs — no runtime dependencies in the browser.

src/
├─ index.ts          # entry: stdio transport + --web-only mode
├─ config.ts         # ports, timeouts, paths
├─ core/             # framework-free domain logic (unit-tested)
│  ├─ svg.ts         #   validate + patch helpers (pure)
│  ├─ store.ts       #   in-memory animation store
│  └─ edits.ts       #   edit-request queue + long-poll
├─ content/          # styles.ts, best-practices.ts (the guidance)
├─ web/server.ts     # Express preview server + SSE
└─ mcp/server.ts     # MCP tools, resources & prompts
public/              # the preview UI (vanilla HTML/CSS/JS)
test/                # node:test specs for core/
bundle/index.mjs     # prebuilt single-file server for the plugin (generated)
.claude-plugin/      # plugin.json + marketplace.json

The plugin ships a prebuilt bundle (npm run bundle, via esbuild) so it runs on node alone with no install step. CI fails if the committed bundle is stale, so run npm run bundle and commit it whenever src/ changes.

License

MIT