gsap-mcp

MCP server for generating GSAP animation code — no runtime dependency, pure static code generation.

Installation

npm install
npm run build

Configuration

Add to your Claude Desktop config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gsap": {
      "command": "node",
      "args": ["/absolute/path/to/gsap-mcp/dist/index.js"]
    }
  }
}

Tools (18)

Core (4)

| Tool | Description | Example Input | |------|-------------|---------------| | gsap_tween | Generate gsap.to/from/fromTo tweens | { "target": ".box", "method": "to", "properties": { "opacity": 1, "x": 100 } } | | gsap_timeline | Build multi-step GSAP timelines | { "steps": [{ "target": ".a", "method": "to", "properties": { "x": 100 } }] } | | gsap_easing | Look up and preview GSAP easing functions | { "action": "lookup", "ease": "power2.out" } | | gsap_preset | Generate common animation presets (fadeIn, slideUp, etc.) | { "preset": "fadeIn", "target": ".hero" } |

Plugins (7)

| Tool | Description | Example Input | |------|-------------|---------------| | gsap_scrolltrigger | ScrollTrigger-powered scroll animations | { "target": ".section", "mode": "standalone", "trigger": ".section" } | | gsap_splittext | SplitText character/word/line animations | { "target": ".heading", "splitType": "chars", "animation": "from" } | | gsap_morphsvg | SVG shape morphing with MorphSVGPlugin | { "target": "#shape1", "shape": "#shape2" } | | gsap_drawsvg | SVG stroke drawing animations | { "target": ".path", "from": "0%", "to": "100%" } | | gsap_motionpath | Animate elements along motion paths | { "target": ".dot", "path": "#circuit" } | | gsap_flip | FLIP animation state transitions | { "targets": ".cards", "action": "full" } | | gsap_textplugin | Text replacement and scramble effects | { "target": ".text", "text": "Hello!", "type": "replace" } |

Dev (7)

| Tool | Description | Example Input | |------|-------------|---------------| | gsap_analyze | Static analysis for performance, best practices, accessibility | { "code": "gsap.to('.box', { width: 100 })" } | | gsap_controls | Play/pause/reverse/seek control code | { "action": "play", "target": "timeline" } | | gsap_utilities | GSAP utility methods (clamp, mapRange, snap, etc.) | { "method": "clamp", "params": { "min": 0, "max": 100, "value": 150 } } | | gsap_matchmedia | Responsive animations with gsap.matchMedia() | { "breakpoints": [{ "name": "Mobile", "query": "(max-width: 768px)", "animations": [] }] } | | gsap_debug | Debug utilities: markers, GSDevTools, logging, slow-motion | { "action": "slowmo", "options": { "timeScale": 0.25 } } | | gsap_performance | FPS monitoring, code optimization, frame profiling | { "action": "monitor", "options": { "metrics": ["fps"] } } | | gsap_framework_integration | Framework-specific code for React/Vue/Angular/Svelte | { "framework": "react", "type": "hook" } |

Architecture

gsap-mcp/
├── src/
│   ├── index.ts                  # Entry point — registers all 18 tools
│   ├── generators/
│   │   ├── code-builder.ts       # Fluent builder for imports + body assembly
│   │   └── templates.ts          # formatGsapVars, formatPosition, wrapInFunction
│   ├── knowledge/
│   │   ├── easings.ts            # Easing function database
│   │   ├── properties.ts         # CSS/GSAP property mappings + performance data
│   │   └── best-practices.ts     # Optimization rules, performance tips, pitfalls
│   └── tools/
│       ├── core/                 # Tween, timeline, easing, presets
│       ├── plugins/              # ScrollTrigger, SplitText, MorphSVG, etc.
│       └── dev/                  # Analyze, controls, utilities, debug, etc.
├── tests/                        # Mirrors src/ structure, 23 test files
├── dist/                         # Built output (tsc)
├── package.json
└── tsconfig.json

Key design decisions:

• No GSAP runtime dependency — the server generates code strings using static knowledge bases and template builders. It never imports or executes GSAP itself.
• Testable core functions — every tool exports a generateXxxCode(params) function that is directly testable without MCP infrastructure.
• MCP SDK pattern — each tool exports a registerXxxTool(server) function that calls server.registerTool() with Zod v4 input schemas.
• CodeBuilder — fluent builder that manages imports, plugin registration, and body lines, then assembles them with build() (full) or buildSnippet() (body only).

Development

# Run all tests
npx vitest run

# Watch mode
npx vitest

# Type-check
npx tsc --noEmit

# Build
npx tsc

# Dev mode (tsx)
npx tsx src/index.ts

Adding a new tool

1. Create src/tools/<category>/<name>.ts
2. Export generateXxxCode(params): XxxResult (testable core logic)
3. Export registerXxxTool(server: McpServer) (MCP registration)
4. Add import + register call in src/index.ts
5. Create tests/tools/<name>.test.ts
6. Run npx tsc --noEmit && npx vitest run

License

MIT