MCP Servers

模型上下文协议服务器、框架、SDK 和模板的综合目录。

G
Gsap MCP
作者 @Lillard01
GitHub 仓库(1 星标)

一个基于Model Context Protocol (MCP)的GSAP动效库服务器，通过自然语言描述生成高质量的GSAP动画代码。

创建于 6/11/2025
更新于 7 months ago
README
View Source
Repository documentation and setup instructions

GSAP MCP Server

License: MIT Node.js Version GSAP Version MCP SDK

一个基于 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 - 滚动触发动画

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

🎨 视觉特效工具

  1. svg_morph_animation - SVG形变动画 💰

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

  2. text_split_animation - 文本分割动画 💰

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

  3. physics_draggable - 拖拽物理效果

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

🔧 性能优化工具

  1. optimize_animation_performance - 性能优化

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

  2. 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 文件

支持和反馈

相关资源

📊 项目状态

✅ 开发完成度

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

🧪 测试状态

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

🔧 已知限制

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

感谢使用 GSAP MCP Server！ 🎉

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

快速设置
此服务器的安装指南

安装包 （如果需要）

npx @modelcontextprotocol/server-gsap-mcp

Cursor 配置 (mcp.json)

{ "mcpServers": { "lillard01-gsap-mcp": { "command": "npx", "args": [ "lillard01-gsap-mcp" ] } } }