# Cavalry Motion App MCP Bridge

A Model Context Protocol (MCP) server that connects AI assistants (like Claude Desktop, Antigravity, Cursor, and ChatGPT) directly to Cavalry, the procedural 2D motion graphics and animation application by Scene Group.

Features

Procedural Layer Creation: Create shapes, text, duplicators, grids, noise generators, color palettes, math nodes, deformers, and particle emitters via natural language.
Dynamic Node Graph Connections: Connect outputs and inputs between nodes (e.g. wire a noise generator to a shape's scale or rotation).
Attribute Control & Keyframing: Inspect and update any property, scrub the timeline, and add animated keyframes.
Scene Introspection: Query active composition metadata, layer hierarchies, and selected nodes.
Render Pipeline: Add compositions to the Render Queue and trigger batch renders.
Raw Script Execution: Execute arbitrary JavaScript against Cavalry’s native api.* module.

Architecture

┌─────────────────────────┐          stdio (MCP)         ┌─────────────────────────────────┐
│ AI Assistant / LLM      │ ◄──────────────────────────► │ Cavalry MCP Server              │
│ (Claude, Antigravity)   │                              │ (TypeScript / Node.js)          │
└─────────────────────────┘                              └────────────────┬────────────────┘
                                                                          │
                                                             HTTP POST    │ (http://127.0.0.1:8080)
                                                                          ▼
                                                         ┌─────────────────────────────────┐
                                                         │ In-Cavalry Script Bridge        │
                                                         │ (MCPBridge.js in Scripts menu)  │
                                                         │ ───► api.create(...)            │
                                                         │ ───► api.set(...)               │
                                                         │ ───► api.connect(...)           │
                                                         └─────────────────────────────────┘

Quick Start

1. Install Dependencies & Build

From this project directory:

npm install
npm run build

2. Install Bridge Script into Cavalry

Run the installer to copy MCPBridge.js to your Cavalry scripts folder:

npm run install-bridge

On Windows, this copies MCPBridge.js to %APPDATA%\Cavalry\Scripts\.

3. Start the Bridge in Cavalry

Launch Cavalry.
Go to the top menu: Scripts → MCPBridge.
A small panel will open showing Status: Online (Port 8080). Keep this open while using the MCP server.

(Alternatively, if you already have the Stallion extension active, it also listens on port 8080 and works seamlessly with this MCP server).

4. Test the Connection

Verify that the MCP server can communicate with Cavalry:

npm run test-connection

MCP Client Configuration

Claude Desktop

Add the following to your claude_desktop_config.json (located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "cavalry": {
      "command": "node",
      "args": [
        "C:/Users/david/Documents/ANTIGRAVITY APP/CALVARY MCP/dist/index.js"
      ],
      "env": {
        "CAVALRY_BRIDGE_PORT": "8080"
      }
    }
  }
}

Antigravity / Cursor / Custom Client

Add to your settings or .cursor/mcp.json:

{
  "mcpServers": {
    "cavalry": {
      "command": "node",
      "args": ["C:/Users/david/Documents/ANTIGRAVITY APP/CALVARY MCP/dist/index.js"]
    }
  }
}

Available MCP Tools

Tool	Description
`cavalry_run_script`	Run arbitrary JavaScript code in Cavalry using `api.*`.
`cavalry_eval_expression`	Evaluate a single expression and return its value.
`cavalry_get_scene_info`	Query active composition name, frame count, FPS, and layer count.
`cavalry_get_comp_layers`	List all layer IDs in the current composition.
`cavalry_get_selected_layers`	Get the IDs of currently selected layers.
`cavalry_create_layer`	Create a new layer/node (`basicShape`, `textShape`, `duplicator`, etc.).
`cavalry_set_attributes`	Set one or more attribute values on a layer.
`cavalry_get_attributes`	Query an attribute value on a layer.
`cavalry_delete_layer`	Delete a layer/node from the scene.
`cavalry_connect_attributes`	Connect source attribute to target attribute in dependency graph.
`cavalry_disconnect_attributes`	Disconnect an attribute connection.
`cavalry_set_frame`	Scrub the playhead to a specific frame.
`cavalry_get_frame`	Get the current frame number.
`cavalry_set_keyframe`	Add a keyframe with value at a specified frame.
`cavalry_playback_control`	Play, stop, or rewind the timeline.
`cavalry_add_to_render_queue`	Add the composition to the Render Manager.
`cavalry_render_queue`	Start rendering items in the queue.

Example Prompts for AI Assistants

1. Animated Noise Grid

"Create a 12x12 grid of rounded squares in Cavalry, attach a noise modifier to their rotation and scale, and set the fill color to electric blue."

2. Kinetic Typography

"Create kinetic text with the headline 'ANTIGRAVITY' in Cavalry. Set the font size to 120, center it, and add a bouncy spring oscillation to the Y position."

3. Radial Burst Animation

"Build a radial burst animation with 24 lines radiating outwards from the center, driven by a step duplicator and keyed to expand from frame 0 to frame 45."

License

MIT