Skip to content
Back to search

moon-animator-mcp

MarketplaceWorks with Claude CodeGitHub

Unofficial MCP server that lets AI agents see, measure and author Moon Animator 2 animations and cutscenes in Roblox Studio.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/deeptutorai--moon-animator-mcp/badge.svg)](/listings/deeptutorai--moon-animator-mcp)

HTML

<a href="/listings/deeptutorai--moon-animator-mcp"><img src="/api/listings/deeptutorai--moon-animator-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One command, then one restart of Studio.

1. Add the server to your MCP client

claude mcp add --scope user moon-animator -- npx -y github:DeepTutorAi/moon-animator-mcp#v0.1.4

For other clients, the equivalent configuration is:

{
  "mcpServers": {
    "moon-animator": {
      "command": "npx",
      "args": ["-y", "github:DeepTutorAi/moon-animator-mcp#v0.1.4"]
    }
  }
}

The first time the server starts it installs its Studio plugin, MoonBridge, into `%LOCALAPPDATA%\Roblox\Plugins`, and keeps it up to date afterwards. Set `MOON_MCP_NO_PLUGIN_INSTALL=1` if you would rather run `install-plugin` yourself.

2. Restart Roblox Studio

Open a place. Studio asks once whether MoonBridge may make HTTP requests to `127.0.0.1`: allow it. Open Moon Animator 2 from the Plugins tab as usual.

3. Check

Ask the agent to call `moon_status`. It reports whether Studio is connected, whether Moon Animator 2 is loaded and which file is open, and says what to do about anything missing. Outside an agent session, this shows the same setup:

npx -y github:DeepTutorAi/moon-animator-mcp#v0.1.4 doctor

Optional: the agent skill

The skill is a field guide for the agent: the order to work in, how joint angles behave, how to get a prop to the mouth, how to cut a camera, and tested recipes. It makes a noticeable difference to the first result.

npx -y github:DeepTutorAi/moon-animator-mcp#v0.1.4 install-skill

This copies the skill to `~/.claude/skills/moon-animator`. Use `--project` to install into the current project's `.claude/skills` instead, or `--dir <folder>` for another client's skills folder.

Alternative: Claude Code plugin (server and skill together)

claude plugin marketplace add DeepTutorAi/moon-animator-mcp
claude plugin install moon-animator@moon-animator-mcp

On Claude Code 2.1.275 or later the same thing is one step inside a session:

/plugin install moon-animator --marketplace DeepTutorAi/moon-animator-mcp

The plugin starts the same server through npx and bundles the same skill. Use it instead of step 1, not as well as it, or the tools will be listed twice.

Why the version is pinned

`#v0.1.4` makes npx run exactly that release. The server runs code inside your Studio session, so the version you run should be one you chose, not whatever was pushed last. To update, change the tag (see [Updating](#updating-and-uninstalling)). Leaving the tag off tracks the newest commit instead.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "moon-animator-mcp",
  3. "owner": { "name": "DeepTutorAi" },
  4. "metadata": {
  5. "description": "Moon Animator 2 tools for AI agents in Roblox Studio."
  6. },
  7. "plugins": [
  8. {
  9. "name": "moon-animator",
  10. "source": "./plugins/moon-animator",
  11. "description": "MCP server and agent field guide for inspecting and authoring Moon Animator 2 animations and cutscenes in Roblox Studio. Requires Moon Animator 2 from the Roblox Creator Store."
  12. }
  13. ]
  14. }
README.md · README · 325 lines
  1. # moon-animator-mcp
  2. An unofficial [Model Context Protocol](https://modelcontextprotocol.io) server
  3. that lets an AI agent see, measure and author
  4. [Moon Animator 2](https://create.roblox.com/store/asset/4725618216) animations
  5. and cutscenes inside Roblox Studio.
  6. The agent works in the same Moon Animator file you do: it looks at the
  7. viewport through the cutscene camera, previews poses before committing them,
  8. writes keyframes with undo, and exports with Moon Animator's own exporter.
  9. ![Storyboard of a four-shot cutscene, each frame labeled with frame, time, shot and subtitle](docs/images/storyboard.jpg)
  10. > **Moon Animator 2 is required and is not included.** It is a separate product
  11. > by its own author. Every user installs it from the Roblox Creator Store. This
  12. > project does not contain, modify or redistribute any Moon Animator code, and
  13. > is not affiliated with or endorsed by its author or by Roblox.
  14. ## What the agent can do
  15. | See | Measure | Author |
  16. | --- | --- | --- |
  17. | Storyboards of a whole cutscene, picked per camera shot | Part positions over time, in world space or relative to another part | Keyframes on rig joints, the camera and any property, one undo step per call |
  18. | Screenshots at any frame, through the cutscene camera or auto-framed on a rig | Foot sliding while planted, jump height, hand-to-face distance | Large rotations (flips, pirouettes, prop twirls) that turn the intended way |
  19. | Pose previews from several sides without writing keyframes | Camera shots: cuts, moves, distances, lens | Rigs, props welded to a hand, camera, subtitles, letterbox |
  20. | Motion trails that show timing, spacing and arcs | Inverse kinematics: joint angles that put a hand or prop on a target | Save, undo, redo, export to KeyframeSequence |
  21. | Pose preview | Motion trail |
  22. | --- | --- |
  23. | ![The same pose from the front, right and three-quarter views](docs/images/pose-preview.jpg) | ![Head, hand and foot paths drawn over a backflip, one dot per sampled frame](docs/images/motion-trail.jpg) |
  24. ![Ten frames of a backflip, framed on the character from the side](docs/images/focus-storyboard.jpg)
  25. ## Requirements
  26. - Windows 10 or 11 (screen capture and the Studio plugin installer are Windows-only)
  27. - [Roblox Studio](https://create.roblox.com/)
  28. - **Moon Animator 2, installed from the [Roblox Creator Store](https://create.roblox.com/store/asset/4725618216)**
  29. - [Node.js](https://nodejs.org/) 20 or newer, and [Git](https://git-scm.com/) (npx installs this package from GitHub)
  30. - An MCP client. The steps below use [Claude Code](https://claude.com/claude-code); any client that runs stdio servers works.
  31. ## Install
  32. One command, then one restart of Studio.
  33. ### 1. Add the server to your MCP client
  34. ```powershell
  35. claude mcp add --scope user moon-animator -- npx -y github:DeepTutorAi/moon-animator-mcp#v0.1.4
  36. ```
  37. For other clients, the equivalent configuration is:
  38. ```json
  39. {
  40. "mcpServers": {
  41. "moon-animator": {
  42. "command": "npx",
  43. "args": ["-y", "github:DeepTutorAi/moon-animator-mcp#v0.1.4"]
  44. }
  45. }
  46. }
  47. ```
  48. The first time the server starts it installs its Studio plugin, MoonBridge,
  49. into `%LOCALAPPDATA%\Roblox\Plugins`, and keeps it up to date afterwards. Set
  50. `MOON_MCP_NO_PLUGIN_INSTALL=1` if you would rather run `install-plugin`
  51. yourself.
  52. ### 2. Restart Roblox Studio
  53. Open a place. Studio asks once whether MoonBridge may make HTTP requests to
  54. `127.0.0.1`: allow it. Open Moon Animator 2 from the Plugins tab as usual.
  55. ### 3. Check
  56. Ask the agent to call `moon_status`. It reports whether Studio is connected,
  57. whether Moon Animator 2 is loaded and which file is open, and says what to do
  58. about anything missing. Outside an agent session, this shows the same setup:
  59. ```powershell
  60. npx -y github:DeepTutorAi/moon-animator-mcp#v0.1.4 doctor
  61. ```
  62. ### Optional: the agent skill
  63. The skill is a field guide for the agent: the order to work in, how joint
  64. angles behave, how to get a prop to the mouth, how to cut a camera, and tested
  65. recipes. It makes a noticeable difference to the first result.
  66. ```powershell
  67. npx -y github:DeepTutorAi/moon-animator-mcp#v0.1.4 install-skill
  68. ```
  69. This copies the skill to `~/.claude/skills/moon-animator`. Use `--project` to
  70. install into the current project's `.claude/skills` instead, or
  71. `--dir <folder>` for another client's skills folder.
  72. ### Alternative: Claude Code plugin (server and skill together)
  73. ```powershell
  74. claude plugin marketplace add DeepTutorAi/moon-animator-mcp
  75. ```
  76. ```powershell
  77. claude plugin install moon-animator@moon-animator-mcp
  78. ```
  79. On Claude Code 2.1.275 or later the same thing is one step inside a session:
  80. ```
  81. /plugin install moon-animator --marketplace DeepTutorAi/moon-animator-mcp
  82. ```
  83. The plugin starts the same server through npx and bundles the same skill. Use
  84. it instead of step 1, not as well as it, or the tools will be listed twice.
  85. ### Why the version is pinned
  86. `#v0.1.4` makes npx run exactly that release. The server runs code inside your
  87. Studio session, so the version you run should be one you chose, not whatever
  88. was pushed last. To update, change the tag (see
  89. [Updating](#updating-and-uninstalling)). Leaving the tag off tracks the newest
  90. commit instead.
  91. ## Using it
  92. With Studio open and Moon Animator showing, ask for what you want:
  93. - "Show me a storyboard of the open cutscene and tell me which shot is weakest."
  94. - "Add an R15 rig named Dancer, give it a microphone in the right hand, and animate a two-second singing pose."
  95. - "The feet slide during the groove between frames 60 and 180. Measure it and fix it."
  96. - "Add a backflip at frame 218, then show me the motion trail of the head."
  97. - "Make the hero's right hook land on the enemy's jaw at frame 30, and check that the fist never passes through the head."
  98. - "Export the animation."
  99. Everything the agent does lands in your Moon Animator file, and each edit is
  100. one step in Moon Animator's undo history.
  101. ## Tools
  102. | Tool | Purpose |
  103. | --- | --- |
  104. | `moon_status` | Connection, Moon Animator state, open file. Call first. |
  105. | `moon_scene` | Items, tracks, keyframes and easing of the open file. |
  106. | `moon_screenshot` | Viewport image at a frame, from the cutscene camera, a custom camera, or auto-framed on an item. |
  107. | `moon_storyboard` | Contact sheet of frames, picked per camera shot or given explicitly. |
  108. | `moon_camera_path` | Shot list: cuts, movement type, distances, lens. |
  109. | `moon_preview_pose` | Images and measurements of a pose without creating keyframes. |
  110. | `moon_motion_trail` | Paths of parts over time with speed, peaks and holds. |
  111. | `moon_sample` | Part positions per frame and a foot-sliding report. |
  112. | `moon_measure` | Distance and surface gap between two points on any items over frames. |
  113. | `moon_solve_reach` | Joint rotations that bring a part to a target, including a point on another item. |
  114. | `moon_open_file` | Open, create or reload a Moon Animator file. |
  115. | `moon_save` | Save the open file. |
  116. | `moon_settings` | Timeline length, fps, loop, export priority. |
  117. | `moon_undo` | Undo or redo Moon Animator actions. |
  118. | `moon_insert_rig` | Place a built-in character rig. |
  119. | `moon_attach_prop` | Weld a prop to a rig part as an animatable joint. |
  120. | `moon_add_items` | Add rigs, the camera, subtitles and effects to the file, or property tracks to an item. |
  121. | `moon_remove_items` | Remove items and their keyframes from the file. |
  122. | `moon_set_keyframes` | Add or update keyframes on joints and properties. |
  123. | `moon_spin` | Key a rotation of any size, with an optional jump arc. |
  124. | `moon_delete_keyframes` | Delete keyframes or clear a track. |
  125. | `moon_export` | Export with Moon Animator's exporter and verify the result. |
  126. ## How it works
  127. ```
  128. MCP client ──stdio── moon-animator-mcp ──HTTP on 127.0.0.1── MoonBridge plugin ── Moon Animator 2
  129. │ (Roblox Studio)
  130. └── window capture (viewport only)
  131. ```
  132. - The MoonBridge plugin long-polls the server on `127.0.0.1` and runs the Luau
  133. snippets it sends. Those snippets call the same functions Moon Animator's own
  134. interface calls, so edits behave exactly like edits made by hand.
  135. - Images are taken from the Studio window and cropped to the 3D viewport. The
  136. Moon Animator window is hidden for the moment of capture and then restored,
  137. along with the timeline position and camera.
  138. - If several agent sessions run at once, the first server hosts the bridge and
  139. the others relay through it.
  140. ## Security
  141. - The bridge listens on `127.0.0.1` only and every request needs a secret
  142. token. The token is generated on first use and stored in
  143. `~/.moon-animator-mcp/bridge-token`; the same value is embedded in your copy
  144. of the Studio plugin.
  145. - The Studio plugin executes Luau sent by the local server. Any program on your
  146. machine that can read the token file can therefore run code in your Studio
  147. session. Do not share the token or your installed `MoonBridge.rbxmx`.
  148. - The server writes one file outside its own data folder: `MoonBridge.rbxmx`
  149. in Studio's plugins folder.
  150. - A tool that runs arbitrary Luau (`moon_exec_luau`) exists for development
  151. and is disabled unless `MOON_MCP_ALLOW_EXEC=1` is set.
  152. ## Configuration
  153. | Variable | Default | Purpose |
  154. | --- | --- | --- |
  155. | `MOON_BRIDGE_PORT` | `47823` | Bridge port. Studio loads one MoonBridge plugin, so every server on this machine must use the same port: a server started with another port rewrites the plugin for that port. |
  156. | `MOON_MCP_HOME` | `~/.moon-animator-mcp` | Where the token is stored. |
  157. | `MOON_MCP_ALLOW_EXEC` | unset | `1` enables `moon_exec_luau`. |
  158. | `MOON_MCP_NO_PLUGIN_INSTALL` | unset | `1` stops the server from installing or updating the Studio plugin. |
  159. | `MOON_MCP_NO_UPDATE_CHECK` | unset | `1` stops the server from looking up the latest release. |
  160. | `MOON_STUDIO_PLUGINS_DIR` | `%LOCALAPPDATA%\Roblox\Plugins` | Where the Studio plugin is installed. |
  161. ## Token cost
  162. - The tool list is about 6,400 tokens (22 tools).
  163. - Results are compact JSON. Long lists are opt-in: `moon_scene` returns
  164. keyframe values only with `values`, `moon_sample` and `moon_preview_pose`
  165. return positions only for the `parts` you name, and `moon_camera_path` and
  166. `moon_motion_trail` keep per-frame data behind `samples` and `detail`.
  167. - Images cost by size. A default storyboard is roughly 1,500 tokens; lower
  168. `cell_width` or `max_width` when a rough look is enough.
  169. Measured on a 6-second cutscene with 319 keyframes:
  170. | Call | Tokens (about) |
  171. | --- | --- |
  172. | `moon_status` | 250 |
  173. | `moon_scene` | 1,800 |
  174. | `moon_scene` with `values` | 4,200 |
  175. | `moon_sample`, foot-sliding check over 120 frames | 280 |
  176. | `moon_camera_path` | 520 |
  177. | `moon_motion_trail` (text part) | 230 |
  178. ## Limitations
  179. - Windows only.
  180. - Tested with Moon Animator 2 version 36000. The server uses Moon Animator's
  181. internal functions, which are not a public API; a Moon Animator update can
  182. break tools until this project catches up. `moon_status` warns when the
  183. installed version differs from the tested one.
  184. - Studio must be in edit mode, with its window not minimized while images are
  185. captured (a minimized window is restored automatically).
  186. - One Studio instance at a time.
  187. - Not available as tools: playing the animation at speed, copy and paste of
  188. keyframes, Moon Animator's Mirror, Stretch and Repeat commands, and importing
  189. an existing animation. Do these in the Moon Animator window.
  190. - Publishing an exported KeyframeSequence to Roblox is left to you.
  191. ## Updating and uninstalling
  192. The server never updates itself. When it starts it reads the latest version
  193. number from this repository (one small request to GitHub; nothing about your
  194. machine is sent) and, if that is newer than the one running, says so: once in
  195. the first tool result of the session, in `moon_status`, and in the server log.
  196. Whether and when to update is up to you.
  197. To update, run this in your project folder, with the version the notice names:
  198. ```powershell
  199. npx -y github:DeepTutorAi/moon-animator-mcp#v<new version> update
  200. ```
  201. It moves the Claude Code registration of the server to that release, keeping
  202. its scope and environment variables, and refreshes every installed copy of the
  203. skill (in `~/.claude/skills` and in the project). Then restart your session.
  204. | Variant | Effect |
  205. | --- | --- |
  206. | `update --check` | Reports what would change and changes nothing. |
  207. | `update --mcp` | Only the server registration. |
  208. | `update --skill` | Only the skill. |
  209. | `update --name <server>` | For a registration that is not named `moon-animator`. |
  210. In other MCP clients, change the tag in the package name by hand. With the
  211. Claude Code plugin, `claude plugin update moon-animator@moon-animator-mcp`
  212. updates server and skill together. The server refreshes the Studio plugin
  213. itself when a release changes it, and `moon_status` says when Studio has to be
  214. restarted to load it.
  215. To remove everything:
  216. ```powershell
  217. npx -y github:DeepTutorAi/moon-animator-mcp#v0.1.4 uninstall-plugin
  218. ```
  219. ```powershell
  220. claude mcp remove moon-animator
  221. ```
  222. Then delete `~/.moon-animator-mcp` and, if installed, the
  223. `~/.claude/skills/moon-animator` folder. For the Claude Code plugin use
  224. `claude plugin uninstall moon-animator@moon-animator-mcp`.
  225. ## Troubleshooting
  226. | Symptom | Fix |
  227. | --- | --- |
  228. | `moon_status` says Studio is not connected | Studio is closed, has not been restarted since the plugin was installed, or the HTTP prompt was declined. In Studio: Plugins tab → Manage Plugins → MoonBridge → allow HTTP requests to `127.0.0.1`. |
  229. | `moon_status` says Moon Animator 2 is not loaded | Install it from the Creator Store, then open it from the Plugins tab. |
  230. | The server does not start in your MCP client | Run `npx -y github:DeepTutorAi/moon-animator-mcp#v0.1.4 --version` in a terminal to see the error. Git and Node.js 20+ must be on `PATH`. |
  231. | An item is marked `stale` | Its rig was deleted or replaced while the file was open. Save, then ask the agent to reopen the file. |
  232. | Images are black or show the wrong area | Leave the Studio window open and unminimized; ask the agent to capture again with `recalibrate`. |
  233. ## Development
  234. ```powershell
  235. git clone https://github.com/DeepTutorAi/moon-animator-mcp
  236. ```
  237. ```powershell
  238. npm test
  239. ```
  240. There are no runtime dependencies. One test file runs the Studio plugin under
  241. the standalone [Luau](https://luau.org) CLI and is skipped when Luau is not
  242. installed (set `MOON_LUAU` to its path). `tools/mcp-call.mjs` calls a single
  243. tool over real MCP stdio, which is handy for trying changes against Studio:
  244. ```powershell
  245. node tools/mcp-call.mjs moon_storyboard "{}" --save storyboard.jpg
  246. ```
  247. Changes per release are listed in [CHANGELOG.md](CHANGELOG.md).
  248. ## License
  249. [MIT](LICENSE). Moon Animator 2 is the property of its author and is licensed
  250. separately; buy it from the Creator Store to use this project and to support
  251. its development.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.