# 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:

```powershell
.\install.ps1
```

Or double-click/run:

```cmd
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:

```powershell
.\install.ps1 -DryRun
```

 `irm` remote command:

```powershell
$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](docs/INSTALLER.md).

## Manual 5-minute setup

1. Install Python 3.10+ and [uv](https://docs.astral.sh/uv/).
2. Open a terminal in this folder.
3. Install the Python environment:

```powershell
uv sync
```

4. Check that the project is healthy:

```powershell
uv run python scripts/doctor.py
```

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

```powershell
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:

```powershell
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:

```toml
[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:

```json
{
  "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](docs/GETTING_STARTED.md)
and [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).

## First prompt to try

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

```text
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:

```text
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](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](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](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

```powershell
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](DESIGN.md) for the architecture.