animation-mcp

Animation MCP lets an AI coding assistant create Roblox combat animations by calling tools instead of hand-editing bones, CFrames, or rig math.

If you are new to MCP: think of this project as a local animation workstation for your AI app. You connect it once in Claude Code, Codex, Cursor, or another MCP client, then ask the AI for moves like "make a fast anime 4-hit M1 combo." The AI calls this server's tools, previews and critiques the result, repairs any mechanical issues, and exports Roblox-ready files.

One-command install

On Windows, open PowerShell in this folder and run:

.\install.ps1

Or double-click/run:

install.cmd

That single command installs dependencies, refreshes project-local MCP configs, registers Codex and Cursor user configs, tries Claude Code registration when the claude CLI is available, and runs the setup doctor.

To preview what it would change:

.\install.ps1 -DryRun

irm remote command:

$env:ANIMMCP_REPO_ZIP="https://github.com/ThatGuyTHD/animation-mcp/archive/refs/heads/main.zip"; irm "https://raw.githubusercontent.com/ThatGuyTHD/animation-mcp/main/install.ps1" | iex

More installer options are in docs/INSTALLER.md.

Manual 5-minute setup

1. Install Python 3.10+ and uv.
2. Open a terminal in this folder.
3. Install the Python environment:

uv sync

4. Check that the project is healthy:

uv run python scripts/doctor.py

5. Print copy/paste config for your AI app:

uv run python scripts/doctor.py --configs

That command prints ready-to-use snippets for Claude Code, Codex, Cursor, and generic MCP clients using the exact path to this checkout.

Connect your AI app

Claude Code

Run this from any terminal, replacing the path if needed:

claude mcp add animation-mcp --scope user -- uv --directory "C:\path\to\Animation MCP" run animation-mcp
claude mcp list

This repo also includes a project-scoped .mcp.json for Claude Code. If you open Claude Code from this project folder, Claude can use that local config instead.

Codex

Add this to ~/.codex/config.toml, or keep the project-scoped .codex/config.toml in this repo:

[mcp_servers.animation-mcp]
command = "uv"
args = ["--directory", "C:/path/to/Animation MCP", "run", "animation-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 300

[mcp_servers.animation-mcp.env]
ANIMMCP_ENGINE = "auto"

Cursor

Cursor can use the included .cursor/mcp.json when this folder is open. For a global install, add this to your Cursor MCP config:

{
  "mcpServers": {
    "animation-mcp": {
      "command": "uv",
      "args": ["--directory", "C:/path/to/Animation MCP", "run", "animation-mcp"],
      "env": {
        "ANIMMCP_ENGINE": "auto"
      }
    }
  }
}

After connecting, open your client's MCP tools view and confirm that animation-mcp exposes tools such as create_rig_session, compose_move, solve_animation, render_preview, critique_motion, and export_for_roblox.

More complete setup paths live in docs/GETTING_STARTED.md and docs/INTEGRATIONS.md.

First prompt to try

Paste this into your AI app after the MCP is connected:

Use animation-mcp to create a fast anime 4-hit Roblox M1 combo for an R15 blocky
rig. Read the style bible and quality gates first. Solve it, render a contact
sheet, critique it, repair mechanical issues if needed, and export Roblox files.

The usual AI workflow is:

create_rig_session
read animmcp://docs/style-bible and animmcp://docs/quality-gates
search_motion_reference / list_pose_library
compose_move
refine with IK, root motion, hit pause, markers, and style modifiers
solve_animation
render_preview
critique_motion
repair_animation if needed
export_for_roblox

Copy/paste workflow prompts are in docs/AI_WORKFLOWS.md.

Requirements

• Python 3.10+ and uv recommended
• Optional: Blender 4.x/5.x for rendered previews, MP4, FBX, and .blend exports. Without Blender, the built-in pure-Python solver still creates animation data and stick-figure contact sheets/GIFs.
• Optional: Roblox Studio plus the companion plugin in roblox/AnimMCPImporter.luau

Optional environment variables:

Var	Meaning	Default
ANIMMCP_ENGINE	auto, blender, or fallback	auto
ANIMMCP_BLENDER_PATH	Explicit blender.exe path	auto-detected
ANIMMCP_EXPORT_DIR	Output directory	./exports
ANIMMCP_ASSETS	Asset library root	./assets

Roblox Studio import

1. Save roblox/AnimMCPImporter.luau as a local Studio plugin.
2. Enable Allow HTTP Requests in Game Settings > Security.
3. Ask your AI to run export_for_roblox(serve=true).
4. In Studio, use Import Animation to pull anim.json from the local server.
5. Use Register Temp Id for quick playtesting, and Build CombatConfig Module for hit windows, damage, knockback, cancel windows, SFX, VFX, and camera shake data.

Outputs land in exports/<move_name>/. When serving is enabled, the Studio plugin reads from http://127.0.0.1:8973/latest/anim.json.

Verify the full pipeline

uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --blender

The first command uses the pure-Python fallback engine. The second also checks Blender rendering and FBX export when Blender is installed.

What this MCP gives the AI

• Semantic animation tools: choreography, poses, fragments, IK targets, root motion, hit pause, markers, timing, and style
• Resources the AI can read: style bible, combat timing, marker vocabulary, export rules, quality gates, bad examples, rigs, poses, grammar, and references
• Quality loop: solve, render, critique, auto-repair mechanical issues, export
• Roblox outputs: anim.json, marker sidecar, combat config JSON, Luau module, and optional FBX/Blend files through Blender

See DESIGN.md for the architecture.