What is Gsap Mcp

GSAP-mcp is a GSAP animation library server based on the Model Context Protocol (MCP), designed to generate high-quality GSAP animation code from natural language descriptions.

Use cases

Use cases include creating dynamic web animations, enhancing user interfaces with smooth transitions, developing engaging game graphics, and generating responsive animations for various screen sizes.

How to use

To use GSAP-mcp, clone the project from GitHub, install the dependencies using npm, run tests, and start the server. Ensure that you have the required system specifications and configure Claude Desktop as needed.

Key features

Key features include intelligent animation generation from natural language, 43 professional tools for various animation types, responsive support for different devices, performance optimization, a rich set of templates, adherence to GSAP best practices, smart degradation for missing commercial plugins, and robust debugging support.

Where to use

GSAP-mcp can be used in web development, game development, interactive media, and any field where high-quality animations are required.

GSAP MCP Server

一个基于 Model Context Protocol (MCP) 的 GSAP 动效库服务器，通过自然语言描述生成高质量的 GSAP 动画代码。支持与 Claude Desktop 无缝集成，让动画开发变得前所未有的简单。

项目状态: ✅ 已完成开发和测试，所有核心功能正常运行，商业插件缺失时提供智能降级方案。

✨ 核心特性

• 🎨 智能动画生成: 通过自然语言描述生成专业的 GSAP 动画代码
• 🔧 43个专业工具: 涵盖基础动画、SVG、文本、物理、3D、响应式等全方位功能
• 📱 响应式支持: 自动生成适配不同设备和屏幕尺寸的动画效果
• 🎯 性能优化: 内置性能监控和优化建议，确保60fps流畅体验
• 🛠️ 丰富模板: 提供现代、经典、创意等多种风格的动画模板
• 📚 最佳实践: 严格遵循 GSAP 官方推荐的最佳实践和性能标准
• 🛡️ 智能降级: 商业插件缺失时自动提供开源替代方案
• 🔍 调试友好: 完整的错误处理、性能监控和调试工具支持

🚀 快速开始

📋 系统要求

组件	版本要求	说明
Node.js	≥ 18.0.0	下载安装
npm	≥ 8.0.0	随 Node.js 自动安装
Claude Desktop	最新版	下载安装
操作系统	macOS 10.15+ / Windows 10+ / Linux	跨平台支持
内存	≥ 4GB RAM	推荐 8GB+
磁盘空间	≥ 500MB	包含依赖和缓存

🎯 浏览器兼容性（生成代码支持）

浏览器	版本	支持状态
Chrome	60+	✅ 完全支持
Firefox	55+	✅ 完全支持
Safari	12+	✅ 完全支持
Edge	79+	✅ 完全支持
iOS Safari	12+	✅ 移动端优化
Android Chrome	60+	✅ 移动端优化

⚡ 一键安装

# 1. 克隆项目
git clone https://github.com/Lillard01/GSAP-mcp.git
cd GSAP-mcp

# 2. 安装依赖
npm install

# 3. 运行测试
npm test

# 4. 启动服务器
npm start

🔧 配置 Claude Desktop

1. 找到配置文件

操作系统	配置文件路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

2. 添加服务器配置

{
  "mcpServers": {
    "gsap-mcp": {
      "command": "node",
      "args": [
        "/your/path/to/gsap-mcp-server/src/index.js"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

3. 重启 Claude Desktop

配置完成后重启 Claude Desktop，你将在对话中看到 🔧 图标，表示 MCP 服务器已成功连接。

🎬 快速演示

在 Claude Desktop 中尝试以下自然语言指令：

"创建一个按钮悬停时放大1.2倍并改变颜色的动画"
"生成一个从左侧滑入的卡片动画，持续0.8秒"
"制作一个滚动时触发的视差背景效果"
"优化这段GSAP代码的性能"

🛠️ 支持的功能

🎯 核心动画能力

• 基础动画: gsap.to() / gsap.from() / gsap.fromTo() / gsap.set()
• 时间轴: 复杂动画序列编排和控制
• 缓动函数: 30+ 内置缓动 + 自定义贝塞尔曲线
• 变换属性: x, y, scale, rotation, skew 等高性能属性
• CSS属性: opacity, color, background 等样式属性

🔌 插件生态系统

插件类别	免费插件	商业插件	降级支持
滚动动画	ScrollTrigger ✅	-	-
拖拽交互	Draggable ✅	ThrowPropsPlugin 💰	✅ 基础惯性
SVG动画	-	MorphSVG 💰, DrawSVG 💰	✅ CSS变换
文本动画	-	SplitText 💰, ScrambleText 💰	✅ CSS动画
物理模拟	-	Physics2DPlugin 💰	✅ 缓动模拟
路径动画	MotionPathPlugin ✅	-	-

💰 = 需要 GSAP Club 会员
✅ = 提供开源替代方案

🧰 完整工具列表

本项目提供 43个专业动画工具，涵盖从基础动画到高级特效的全方位需求。

📊 工具分类概览

分类	工具数量	主要功能	商业插件依赖
🎯 基础动画	8个	核心动画、时间轴、交错效果	无
🎨 SVG动画	6个	路径变形、绘制、滤镜效果	2个工具需要
📝 文本动画	5个	分割、打字机、扰乱效果	2个工具需要
⚡ 物理动画	4个	拖拽、碰撞、弹簧效果	2个工具需要
🌐 3D动画	4个	变换、相机、光照效果	无
📱 响应式	3个	断点、缩放、方向适配	无
🔧 调试优化	3个	性能监控、调试工具	无
🔄 批处理	3个	批量动画、序列处理	无
⏱️ 时序控制	3个	同步时间轴、拖拽控制	无
🎛️ 高级控制	4个	精确控制、复杂效果	无

🔥 热门工具推荐

🎯 必备基础工具

1. generate_gsap_animation - 智能动画生成器

   "创建一个淡入动画，持续1秒，使用弹性缓动"
   

2. create_timeline_animation - 复杂动画序列

   "制作一个卡片翻转然后滑动的连续动画"
   

3. generate_scroll_animation - 滚动触发动画

   "当元素进入视口时从下方滑入"
   

🎨 视觉特效工具

4. svg_morph_animation - SVG形变动画 💰

   "将圆形变形为星形，持续2秒"
   

5. text_split_animation - 文本分割动画 💰

   "让标题的每个字母依次飞入"
   

6. physics_draggable - 拖拽物理效果

   "创建一个可拖拽的卡片，带有惯性效果"
   

🔧 性能优化工具

7. optimize_animation_performance - 性能优化

   "优化这段动画代码，目标60fps"
   

8. performance_monitor - 性能监控

   "添加帧率监控和内存使用统计"
   

💰 标记的工具需要 GSAP 商业许可证，但提供免费的降级替代方案

SVG动画工具

7. svg_morph_animation

生成SVG形变动画

参数：

• fromPath (string, 必需): 起始路径
• toPath (string, 必需): 目标路径
• duration (number, 可选): 动画时长，默认2秒
• ease (string, 可选): 缓动函数，默认’power2.inOut’
• repeat (number, 可选): 重复次数，默认0
• yoyo (boolean, 可选): 往返播放，默认false

8. svg_draw_animation

生成SVG描边动画

参数：

• selector (string, 必需): SVG路径选择器
• duration (number, 可选): 动画时长，默认2秒
• ease (string, 可选): 缓动函数，默认’none’
• direction (string, 可选): 绘制方向 (forward, reverse)，默认’forward’
• autoStart (boolean, 可选): 自动开始，默认true

9. svg_path_animation

生成SVG路径动画

参数：

• pathSelector (string, 必需): 路径选择器
• elementSelector (string, 必需): 移动元素选择器
• duration (number, 可选): 动画时长，默认3秒
• ease (string, 可选): 缓动函数，默认’none’
• autoRotate (boolean, 可选): 自动旋转，默认true
• align (string, 可选): 对齐方式，默认’center’

10. svg_filter_animation

生成SVG滤镜动画

参数：

• selector (string, 必需): SVG元素选择器
• filterType (string, 必需): 滤镜类型 (blur, brightness, contrast, saturate)
• fromValue (number, 必需): 起始值
• toValue (number, 必需): 目标值
• duration (number, 可选): 动画时长，默认1秒
• ease (string, 可选): 缓动函数，默认’power2.out’

文本动画工具

11. text_split_animation

生成文本分割动画

参数：

• selector (string, 必需): 文本元素选择器
• splitType (string, 必需): 分割类型 (chars, words, lines)
• animationType (string, 必需): 动画类型
• stagger (number, 可选): 交错延迟，默认0.05
• duration (number, 可选): 单个动画时长，默认0.6
• ease (string, 可选): 缓动函数，默认’back.out(1.7)’

12. typewriter_animation

生成打字机动画

参数：

• selector (string, 必需): 文本元素选择器
• text (string, 必需): 要显示的文本
• speed (number, 可选): 打字速度，默认0.05
• cursor (boolean, 可选): 显示光标，默认true
• cursorChar (string, 可选): 光标字符，默认’|’
• loop (boolean, 可选): 循环播放，默认false

13. text_scramble_animation

生成文本扰乱动画

参数：

• selector (string, 必需): 文本元素选择器
• finalText (string, 必需): 最终文本
• scrambleChars (string, 可选): 扰乱字符集，默认’!<>-_/[]{}—=+*^?#________’
• revealDelay (number, 可选): 揭示延迟，默认0.1
• scrambleDuration (number, 可选): 扰乱持续时间，默认1

14. text_path_animation

生成文本路径动画

参数：

• textSelector (string, 必需): 文本选择器
• pathSelector (string, 必需): 路径选择器
• duration (number, 可选): 动画时长，默认3秒
• ease (string, 可选): 缓动函数，默认’none’
• autoRotate (boolean, 可选): 自动旋转，默认true
• splitType (string, 可选): 分割类型，默认’chars’

物理动画工具

15. draggable_animation

生成拖拽动画

参数：

• selector (string, 必需): 可拖拽元素选择器
• type (string, 可选): 拖拽类型 (x, y, rotation)，默认’x,y’
• bounds (string, 可选): 边界限制
• inertia (boolean, 可选): 惯性效果，默认true
• snap (object, 可选): 吸附配置
• onDrag (string, 可选): 拖拽回调函数

16. inertia_animation

生成惯性动画

参数：

• selector (string, 必需): 元素选择器
• velocityX (number, 可选): X轴初始速度，默认0
• velocityY (number, 可选): Y轴初始速度，默认0
• resistance (number, 可选): 阻力系数，默认3000
• minDuration (number, 可选): 最小持续时间，默认0.1
• maxDuration (number, 可选): 最大持续时间，默认3

17. physics_2d_animation

生成2D物理动画

参数：

• selector (string, 必需): 元素选择器
• gravity (number, 可选): 重力，默认1000
• friction (number, 可选): 摩擦力，默认0.8
• bounce (number, 可选): 弹性，默认0.7
• initialVelocity (object, 可选): 初始速度
• boundaries (object, 可选): 边界设置

18. collision_animation

生成碰撞检测动画

参数：

• elements (array, 必需): 碰撞元素配置
• onCollision (string, 可选): 碰撞回调函数
• tolerance (number, 可选): 碰撞容差，默认1
• continuous (boolean, 可选): 持续检测，默认true
• visualDebug (boolean, 可选): 可视化调试，默认false

3D动画工具

19. transform_3d_animation

生成3D变换动画

参数：

• selector (string, 必需): 3D元素选择器
• rotationX (number, 可选): X轴旋转，默认0
• rotationY (number, 可选): Y轴旋转，默认0
• rotationZ (number, 可选): Z轴旋转，默认0
• z (number, 可选): Z轴位移，默认0
• perspective (number, 可选): 透视距离，默认1000
• duration (number, 可选): 动画时长，默认2秒

20. cube_3d_animation

生成3D立方体动画

参数：

• containerSelector (string, 必需): 容器选择器
• size (number, 可选): 立方体尺寸，默认200
• autoRotate (boolean, 可选): 自动旋转，默认true
• rotationSpeed (number, 可选): 旋转速度，默认1
• enableInteraction (boolean, 可选): 启用交互，默认true
• faces (array, 可选): 面配置

21. flip_card_3d_animation

生成3D翻转卡片动画

参数：

• cardSelector (string, 必需): 卡片选择器
• trigger (string, 可选): 触发方式 (hover, click)，默认’hover’
• direction (string, 可选): 翻转方向 (horizontal, vertical)，默认’horizontal’
• duration (number, 可选): 动画时长，默认0.6秒
• ease (string, 可选): 缓动函数，默认’power2.inOut’
• perspective (number, 可选): 透视距离，默认1000

22. parallax_3d_animation

生成3D视差滚动动画

参数：

• layers (array, 必需): 视差层配置
• intensity (number, 可选): 视差强度，默认0.5
• smoothness (number, 可选): 平滑度，默认0.1
• enableGyroscope (boolean, 可选): 启用陀螺仪，默认false
• boundaries (object, 可选): 边界限制

批量操作工具

23. stagger_animation

生成交错动画效果

参数：

• selector (string, 必需): 元素选择器
• animationType (string, 必需): 动画类型
• stagger (number, 可选): 交错延迟，默认0.1
• from (string, 可选): 交错起点 (start, end, center, edges)，默认’start’
• duration (number, 可选): 单个动画时间，默认1
• ease (string, 可选): 缓动函数，默认’power2.out’

24. sequence_animation

生成序列动画效果

参数：

• elements (array, 必需): 元素序列配置
• globalDuration (number, 可选): 总动画时间，默认5
• repeat (number, 可选): 重复次数，默认0
• yoyo (boolean, 可选): 往返播放，默认false
• autoPlay (boolean, 可选): 自动播放，默认true

25. batch_animation_generator

生成批量动画生成器

参数：

• baseSelector (string, 必需): 基础选择器
• count (number, 必需): 元素数量
• animationTemplate (object, 必需): 动画模板
• randomization (object, 可选): 随机化配置
• batchSize (number, 可选): 批处理大小，默认10

26. batch_scroll_animation

生成批量滚动动画

参数：

• elementsSelector (string, 必需): 元素选择器
• animationConfig (object, 必需): 动画配置
• scrollConfig (object, 可选): 滚动配置
• stagger (number, 可选): 交错延迟，默认0.2
• batch (number, 可选): 批处理数量，默认3

调试工具

27. performance_monitor

生成性能监控代码

参数：

• monitorFPS (boolean, 可选): 监控帧率，默认true
• monitorMemory (boolean, 可选): 监控内存，默认true
• logInterval (number, 可选): 日志间隔(ms)，默认1000
• displayStats (boolean, 可选): 显示统计信息，默认true
• alertThresholds (object, 可选): 警告阈值

28. animation_debugger

生成动画调试器代码

参数：

• enableTimeline (boolean, 可选): 启用时间轴调试，默认true
• enableControls (boolean, 可选): 启用控制面板，默认true
• logAnimations (boolean, 可选): 记录动画日志，默认true
• visualizeProgress (boolean, 可选): 可视化进度，默认true
• breakpoints (array, 可选): 调试断点

29. memory_manager

生成内存管理器代码

参数：

• autoCleanup (boolean, 可选): 自动清理，默认true
• cleanupInterval (number, 可选): 清理间隔(ms)，默认30000
• memoryThreshold (number, 可选): 内存阈值(MB)，默认100
• trackAnimations (boolean, 可选): 跟踪动画，默认true
• generateReport (boolean, 可选): 生成报告，默认false

响应式动画工具

30. responsive_animation

生成响应式动画效果

参数：

• selector (string, 必需): 响应式元素选择器
• breakpoints (object, 必需): 断点配置
• animations (object, 必需): 各断点动画配置
• enableOrientationChange (boolean, 可选): 启用方向变化，默认true
• enableResizeThrottle (boolean, 可选): 启用大小变化节流，默认true
• throttleDelay (number, 可选): 节流延迟，默认100

31. device_adaptive_animation

生成设备适配动画

参数：

• selector (string, 必需): 设备适配元素选择器
• deviceConfigs (object, 必需): 设备配置
• enableTouchDetection (boolean, 可选): 启用触摸检测，默认true
• enableHoverDetection (boolean, 可选): 启用悬停检测，默认true
• autoStart (boolean, 可选): 自动开始，默认true

32. media_query_animation

生成媒体查询动画

参数：

• selector (string, 必需): 媒体查询元素选择器
• mediaQueries (object, 必需): 媒体查询配置
• enableOrientationQueries (boolean, 可选): 启用方向查询，默认true
• enablePrintQueries (boolean, 可选): 启用打印查询，默认false
• autoStart (boolean, 可选): 自动开始，默认true

33. container_query_animation

生成容器查询动画

参数：

• containerSelector (string, 必需): 容器选择器
• elementSelector (string, 必需): 元素选择器
• sizeBreakpoints (object, 必需): 尺寸断点
• animations (object, 必需): 动画配置
• observeResize (boolean, 可选): 观察大小变化，默认true
• throttleDelay (number, 可选): 节流延迟，默认100

📖 使用示例

🎯 基础动画示例

// 在Claude Desktop中使用
"请使用generate_gsap_animation工具创建一个卡片悬停动画，当鼠标悬停时卡片向上移动10px并增加阴影"

🎬 复杂动画序列

// 创建多步骤动画
"使用create_timeline_animation创建一个页面加载动画：
1. 标题从上方滑入
2. 内容淡入
3. 按钮从下方弹出
每个动画间隔0.2秒"

📱 滚动触发动画

// 滚动动画示例
"用generate_scroll_animation创建视差滚动效果，背景图片滚动速度是内容的50%"

🎨 SVG动画示例

// SVG路径动画
"创建一个SVG logo绘制动画，路径从0%到100%绘制，持续3秒"

🔧 代码示例

基础动画

// 淡入动画
gsap.to(".element", {
  opacity: 1,
  duration: 1,
  ease: "power2.out"
});

滚动动画

// 滚动触发的视差效果
gsap.registerPlugin(ScrollTrigger);

gsap.to(".parallax", {
  y: -100,
  scrollTrigger: {
    trigger: ".parallax",
    start: "top bottom",
    end: "bottom top",
    scrub: true
  }
});

时间轴动画

// 复杂动画序列
const tl = gsap.timeline();
tl.to(".box1", { x: 100, duration: 1 })
  .to(".box2", { y: 100, duration: 1 }, "-=0.5")
  .to(".box3", { rotation: 360, duration: 1 });

💬 自然语言示例

在Claude Desktop中，你可以这样描述动画需求：

• “创建一个按钮悬停时放大1.1倍的动画效果”
• “生成一个从左侧滑入并淡入的卡片动画”
• “制作一个滚动时触发的视差背景效果”
• “优化这段GSAP代码的性能，目标60fps”

开发和调试

开发模式

npm run dev  # 启动开发服务器，支持热重载

测试

npm test     # 运行所有测试

使用MCP Inspector调试

# 启动调试界面
npx @modelcontextprotocol/inspector node src/index.js

# 在浏览器中打开 http://localhost:3000 查看调试信息

查看演示页面

# 在浏览器中打开
open example.html  # macOS
start example.html # Windows
xdg-open example.html # Linux

故障排除

常见问题

1. 安装依赖失败

# 清除缓存并重新安装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

2. 权限错误（macOS/Linux）

# 使用sudo安装全局包
sudo npm install -g @modelcontextprotocol/inspector

# 或者配置npm使用不同目录
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

3. 网络问题

# 配置npm镜像源
npm config set registry https://registry.npmmirror.com

# 或者使用代理
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

4. Claude Desktop无法连接MCP服务器

• 检查配置文件路径是否正确
• 确保Node.js路径正确
• 查看Claude Desktop的错误日志
• 重启Claude Desktop应用

5. 生成的动画代码不工作

• 确保页面已加载GSAP库
• 检查目标元素选择器是否正确
• 验证CSS属性是否可动画化
• 查看浏览器控制台错误信息

日志和调试

查看服务器日志

# 开发模式下的详细日志
DEBUG=* npm run dev

# PM2管理的服务日志
pm2 logs gsap-mcp-server

启用调试模式

# 设置环境变量
export DEBUG=gsap-mcp:*
npm start

性能优化

服务器性能

• 使用PM2进行进程管理
• 配置适当的内存限制
• 启用集群模式（多核CPU）

动画性能

• 优先使用transform属性（x, y, scale, rotation）
• 避免动画layout属性（width, height, top, left）
• 使用will-change CSS属性
• 合理设置动画帧率

更新和维护

检查更新

# 检查过时的包
npm outdated

# 更新依赖
npm update

# 修复安全漏洞
npm audit fix

版本管理

# 查看当前版本
npm version

# 发布新版本
npm version patch  # 补丁版本
npm version minor  # 次要版本
npm version major  # 主要版本

GSAP许可证说明

免费使用

• 个人项目和开源项目可免费使用GSAP标准功能
• 包括基础动画、Timeline、大部分缓动函数

商业许可证

• 商业项目可能需要购买GSAP许可证
• 某些高级插件需要付费许可证
• 详情请访问：GSAP许可证页面

许可证检查

// 检查GSAP许可证状态
console.log(gsap.version);
console.log(gsap.license);

贡献指南

开发环境设置

# Fork项目并克隆
git clone https://github.com/your-username/gsap-mcp-server.git
cd gsap-mcp-server

# 安装开发依赖
npm install

# 创建功能分支
git checkout -b feature/new-feature

代码规范

• 使用ESLint和Prettier进行代码格式化
• 遵循JavaScript标准代码风格
• 添加适当的注释和文档
• 编写单元测试

提交代码

# 运行测试
npm test

# 提交更改
git add .
git commit -m "feat: add new animation feature"
git push origin feature/new-feature

# 创建Pull Request

许可证

MIT License - 详见 LICENSE 文件

支持和反馈

• 🐛 Bug报告: GitHub Issues
• 💡 功能建议: GitHub Discussions
• 📧 邮件支持: [email protected]
• 📚 文档: 项目Wiki

相关资源

• GSAP官方文档
• Model Context Protocol
• Claude Desktop
• Node.js官网
• npm包管理器

📊 项目状态

✅ 开发完成度

• 核心功能: 100% 完成
• 工具实现: 43/43 工具全部实现
• 测试覆盖: 所有主要功能已测试
• 文档完整性: 完整的使用文档和API说明
• 错误处理: 完善的错误处理和降级机制

🧪 测试状态

• ✅ MCP服务器启动测试通过
• ✅ 所有工具响应测试通过
• ✅ 插件降级机制测试通过
• ✅ 代码生成质量验证通过
• ✅ 性能优化功能测试通过

🔧 已知限制

• 6个商业插件需要GSAP Club会员（已提供降级方案）
• 生成的代码需要在浏览器环境中运行
• 复杂3D动画可能需要额外的性能优化

---

感谢使用 GSAP MCP Server！ 🎉

如果这个项目对你有帮助，请考虑给我们一个 ⭐ Star！