GSAP MCP Server

An MCP server that gives an AI coding agent the official GreenSock GSAP skills — not a paraphrase of them.

The skills published at greensock/gsap-skills are vendored into this repository and served as MCP resources. Every answer, every generated snippet and every validation rule traces back to one of them, and cites which. Where the skills do not cover something, this server says so rather than filling the gap with invention.

Targets GSAP 3.15.0, the release the vendored skills are written against.

Install

Published on npm as @osaidrajput9/gsap-mcp, so a client fetches a prebuilt package — no compile step on first launch.

Don't npm install this into your project. It is a tool your coding agent runs, not a library your app imports, so adding it to package.json only drags it through every CI run and deploy.

Installing it also registers nothing. An MCP server exists only where a config file names a command to run — nothing scans node_modules looking for one, and a bin entry does not announce itself. The config below is the entire installation, and npx -y fetches the package the first time the server starts.

Claude Code, per project (works in cloud sessions)

Put a .mcp.json at the root of the project you want the server in, and commit it:

{
  "mcpServers": {
    "gsap": {
      "command": "npx",
      "args": ["-y", "@osaidrajput9/gsap-mcp"]
    }
  }
}

This is the only route that works in a remote or cloud Claude Code session. claude mcp add writes to a config file on the machine running the claude binary, so it cannot register anything from an ephemeral container. Project scope is read from the repository checkout instead, and is shared with anyone who clones it. Claude Code asks to approve a project-scoped server the first time it sees one.

Claude Code, for yourself

claude mcp add gsap -- npx -y @osaidrajput9/gsap-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gsap": {
      "command": "npx",
      "args": ["-y", "@osaidrajput9/gsap-mcp"]
    }
  }
}

Continue.dev

~/.continue/config.yaml:

mcpServers:
  - name: gsap
    command: npx
    args:
      - "-y"
      - "@osaidrajput9/gsap-mcp"

From a local clone

git clone https://github.com/osaidrajput9/gsap-mcp
cd gsap-mcp
npm install        # `prepare` builds automatically
npm start

Point your client at node /absolute/path/to/gsap-mcp/dist/index.js.

Installing from a git checkout instead

"args": ["-y", "github:osaidrajput9/gsap-mcp"]

Still works, and tracks main rather than the last release. The cost is a build on install: prepare compiles TypeScript on the client's machine, which measured 12.9s cold and 2.1s warm against 5.6s and 0.92s from the registry.

Tools

All eight are read-only (readOnlyHint): they read vendored files and return text. None writes to disk, spawns a process, or makes a network request.

| Tool | What it does | | :--- | :--- | | get_gsap_guidance | Returns the official skill covering a topic, routed through the trigger terms GreenSock publishes in llms.txt. Start here. | | validate_gsap_code | Fourteen deterministic checks against the skills, with line numbers, suggested fixes and the rule each finding comes from. | | get_gsap_api_expert | Quotes the skill sections documenting a method, property or plugin. | | understand_and_create_animation | Generates a snippet for a named pattern. Without a pattern, returns the matching skills and the catalog rather than guessing. | | create_production_pattern | Renders a ready-made pattern for a framework. | | generate_complete_setup | Install commands, plugin registration and a starter component. | | debug_animation_issue | Routes a reported problem to the skills, with a checklist parsed from their own "Do Not" sections. | | optimize_for_performance | Returns the official performance guidance. Reports what to change; never rewrites your code. |

Patterns

scroll-reveal, parallax, pinned-section, horizontal-scroll, text-reveal, scroll-text-fill, timeline-sequence, hover-interaction, draggable, loading-sequence, page-transition, data-viz, smooth-scroll-lenis.

The two text patterns differ in the one way that matters: text-reveal slides lines in once when they enter, while scroll-text-fill fills words in locked to the scrollbar, emptying again on the way back up. Pick the second for the "text lights up as you read" effect.

Each renders for react, nextjs, vue, nuxt, svelte or vanilla.

Every generated snippet gets, by construction rather than by template discipline:

• gsap.matchMedia() with both prefers-reduced-motion queries. A matchMedia handler only runs when a condition matches, so reduce alone would leave everyone without the preference with no animation at all.
• Scoped selectors — scope for useGSAP, the third argument to mm.add() elsewhere. The scope is a wrapper around the markup, never the markup root: a scoped selector never matches the scope element itself, so a container sitting on the root would silently resolve a trigger pointing at that root to null.
• Teardown that reverts only what the component created.
• Registered plugins, imported from the public gsap package.
• Transforms rather than layout properties, and autoAlpha rather than opacity.

smooth-scroll-lenis is the one pattern not covered by the official skills; it is labelled as such wherever it appears. GSAP's own smooth-scroll plugin is ScrollSmoother.

Resources

| URI | Contents | | :--- | :--- | | gsap://skills/index | The upstream llms.txt discovery index, plus provenance | | gsap://skills/license | GreenSock's MIT license for the vendored files | | gsap://skills/errata | Where the official skills are wrong, and what GSAP actually does | | gsap://skills/gsap-core | Tweens, easing, stagger, transforms, matchMedia | | gsap://skills/gsap-timeline | Timelines, position parameter, labels, nesting | | gsap://skills/gsap-scrolltrigger | ScrollTrigger: pinning, scrub, batch, refresh | | gsap://skills/gsap-plugins | Every plugin, registration, licensing | | gsap://skills/gsap-react | useGSAP, refs, contextSafe, SSR | | gsap://skills/gsap-frameworks | Vue, Nuxt, Svelte lifecycles | | gsap://skills/gsap-performance | Transforms, quickTo, batching | | gsap://skills/gsap-utils | clamp, mapRange, snap, toArray, distribute |

Each is the SKILL.md byte-for-byte, frontmatter included — including the parts known to be wrong. A vendored skill is worth serving because it is provably GreenSock's text and not ours; annotating the body would end that.

Corrections live beside it instead, in src/data/errata.ts. Every tool that quotes a skill appends the entries that apply to what it returned, the affected resource says so in its description, and gsap://skills/errata lists them all. Each entry records how it was established — by running GSAP, not by reading it.

test/errata.test.ts ties every entry to the text it describes: a correction's quotes must still appear upstream, and a documented gap's pattern must still match nothing. When GreenSock fixes something, that test fails and names the entry to delete, so a correction cannot outlive its error and become a second source of wrong answers.

Currently two entries, both verified against GSAP 3.15.0:

• refresh-priority-direction — the ScrollTrigger table says refreshPriority is "Lower = refreshed first". It is the opposite: ScrollTrigger.sort multiplies the value by -1e6, so higher refreshes first. The skill's practical advice is backwards too. Reported by a user after it caused two bugs.
• stagger-function-form — the skills document stagger as a number and as an object, never as a function. (index, target, targets) => seconds works and is the form to reach for when the offset depends on the element.

Structure

src/
  index.ts              stdio entry point
  server.ts             McpServer assembly (registerTool + Zod schemas)
  data/
    skills/             vendored skills — MIT, (c) 2026 GreenSock
      SOURCE.json       upstream commit, sync date, targeted GSAP release
      LICENSE
    skills.ts           loader, frontmatter and llms.txt parsing
  lib/
    skill-search.ts     whole-word routing, section lookup, rule extraction
    source-scan.ts      lexical scanning for the validator
  resources/skills.ts   gsap://skills/* resources
  generators/
    framework.ts        per-framework shells
    patterns.ts         the pattern catalog
    setup.ts            project boilerplate
  tools/                one module per tool
scripts/
  copy-assets.mjs       copies skills into dist/ (tsc emits only JS)
  sync-skills.mjs       refreshes the vendored skills
test/                   Vitest suites and fixtures

Never hand-edit src/data/skills/. It is replaced wholesale by the sync.

Staying current

.github/workflows/sync-skills.yml runs weekly, refreshes the vendored skills, and opens a pull request only when upstream actually changed. It builds and tests first, so a sync that breaks the server is never proposed. It publishes nothing.

Run it by hand with:

git clone --depth 1 https://github.com/greensock/gsap-skills /tmp/gsap-skills
node scripts/sync-skills.mjs --from /tmp/gsap-skills
npm test

Development

npm install
npm run build     # tsc, then copy the skill files into dist/
npm test          # builds first, then runs Vitest
npm run test:watch

800 tests. The suite parses all 78 pattern × framework combinations, round-trips the generated code back through validate_gsap_code, and drives the built server over a real stdio subprocess. GreenSock's own examples/ are vendored as fixtures: if the validator reports an error on that code, the validator is wrong.

test/browser.test.ts loads every vanilla snippet into Chromium with real GSAP 3.15.0 and asserts the animations happen: the timeline runs and settles, ScrollTrigger.batch fires on scroll, the parallax layer scrubs, SplitText splits and masks, both prefers-reduced-motion branches run, and every ScrollTrigger resolves a real trigger element. It skips itself when no Chromium is available, so the rest of the suite runs anywhere; force the skip with GSAP_MCP_SKIP_BROWSER_TESTS=1.

test/react-browser.test.ts goes further for React: it bundles each generated component into a real React 19 app and mounts it. The key check is a decoy — markup carrying the same classes rendered outside the component. A scoped selector must never reach it. That, plus unmount teardown and contextSafe handlers, is what the static checks cannot establish.

test/acceptance-hero.test.ts is the end-to-end one: it drives the built server over stdio exactly as a client does, asks for an interactive hero section in plain language, takes the returned code verbatim, feeds it back to validate_gsap_code, then composes the two generated components into one page and mounts it. It covers what a real build actually looks like — two patterns side by side, each with its own useGSAP and gsap.matchMedia() — and checks keyboard reachability, reduced motion, cross-component scoping and teardown.

test/vue-svelte-browser.test.ts does the same for the remaining two frameworks: it compiles each generated Vue SFC and Svelte component and mounts them. Neither has useGSAP to fall back on, so the scope passed to mm.add() is the only thing confining selectors there — verified by removing it, at which point the decoy animates and the test fails.

All six frameworks are now verified by execution, not by construction.

test/line-endings.test.ts converts the vendored skills to CRLF and asserts every parser still finds its sections and rules. Git on Windows checks files out that way by default, and JavaScript's . does not match \r, so a Linux-only suite cannot see the difference.

Releasing

npm version patch   # or minor / major
npm publish

prepublishOnly runs the full suite and prepare builds dist/, so a broken build cannot reach the registry. Publishing is manual and stays that way: .github/workflows/ holds no publish step and no registry credential, and test/workflows.test.ts fails if either ever appears.

publishConfig.access is set to public because scoped packages default to restricted, which needs a paid npm account.

Credits

• Vinh Nguyen — original gsap-mcp.
• GreenSock — GSAP itself and the official agent skills this server is built on, vendored under their MIT license.

MIT. See LICENSE; the vendored skills carry GreenSock's own MIT license at src/data/skills/LICENSE.