PinePaper Studio MCP server

PinePaper MCP Server

Create animated vector graphics with AI using the Model Context Protocol

English · 简体中文 · 日本語 · 한국어 · Español · Português (BR) · Français · Deutsch · हिन्दी

Everything above and below moves — these are animated SVGs exported straight from PinePaper tool calls, no video files, no GIFs. Open this README on GitHub and watch.

Overview

PinePaper MCP Server enables AI assistants to create and animate graphics in PinePaper Studio via the Model Context Protocol (MCP). Works with any AI that supports MCP tool calling (Claude, GPT, Gemini, local models, etc.).

The server exposes 178 tools across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:

• Create geometric shapes, text collages, diagrams, and data charts
• Apply 37+ character-level text effects and 28+ vertex deformation presets
• Wire behavioral relationships between objects (orbit, follow, point-at, mirror, parallax, morph)
• Animate with keyframes, timeline sequencing, and physics simulations
• Build interactive widgets with click/hover/drag event bindings
• Export to SVG, self-contained interactive HTML, MP4, and animated formats

Running it: local or hosted

Local is free and complete. Every one of the 178 tools works when you run this server yourself. There is no reduced tier and nothing held back.

What it needs:

Node	22.13 or newer (any supported Node release: 22, 24 or 26)
Disk	With Puppeteer (below), Chrome is downloaded on install — roughly 320 MB per version
Memory	a Chrome process plus the Studio canvas, so budget ~1 GB while a job runs

That is fine on a laptop and awkward on a small VPS, a locked-down work machine, or a container you would rather keep thin.

cloud.pinepaper.studio runs the same server for you — same tools, same version, over HTTP with no install and no browser on your machine. It exists for three cases: you have no MCP client, you cannot install one, or your machine cannot spare the browser.

Hosting costs money, so the hosted option is paid — it runs on credits. See cloud.pinepaper.studio for current pricing. Run it locally if you can, but it is not identical, and the differences run both ways.

The hosted service runs a tested set of LLMs, repairs generated code before it reaches the canvas — which a local server structurally cannot do for itself — and encodes video server-side, in an ffmpeg container that owns the job durably. Locally, an export runs in your own browser: it needs Chrome and Puppeteer, it is bounded by your machine, and a long render occupies that browser for its duration.

What the local server has instead is the whole tool surface. Tools that need the editor's UI — selection, drag-and-drop, mode toggles — work here against a visible browser and are excluded from headless operation. Which model to trust is a question you can answer yourself rather than take on trust: a benchmark runs one prompt across several models and puts the results side by side, any run shareable. It is in invite-only beta.

FFmpeg is yours to install

The MCP server does not include, download or install FFmpeg, and PinePaper does not provide an FFmpeg build. If you want it, install it yourself from ffmpeg.org or your package manager. Your copy comes under FFmpeg's own licence and the licences of whatever codecs your build includes, and following those terms is up to you.

Most exports don't need it: MP4, WebM and the other formats are made in your browser. You need your own FFmpeg for these:

• An MP4 that repeats byte for byte, on a machine where the browser's encoder won't. The export warns with determinism_not_pinned when that happens. Export the frames with pinepaper_interchange (export_png_sequence, passing duration and fps), unzip them, and encode:

  ffmpeg -framerate 30 -i frame_%05d.png -c:v libx264 -pix_fmt yuv420p -crf 18 -threads 1 out.mp4
  

  Match -framerate to the fps you exported, and use a build that includes libx264. Keep -threads 1, because x264 can vary between runs when it uses several threads under a bitrate cap. The file repeats when the browser build, the FFmpeg build and the settings stay the same, but a different browser build can produce different frames. The frames carry no audio, so add any sound in FFmpeg.

• Formats browsers can't encode, such as ProRes and HAP, from the same frames.

• In the Claude Desktop extension, joining a perScene export and checking a saved video. These use the ffmpeg and ffprobe on your PATH; the extension bundles a small script that starts them, not the programs themselves. Without them, a perScene export runs whole and the check is skipped. The npm package never starts FFmpeg.

Quick start

Claude Desktop: download pinepaper-mcp-server.mcpb and open it. Desktop installs the server, with no config file to edit. It drives your installed Google Chrome; its settings choose another Chromium-based browser, the export folder and the tool list. Each release lists the file's SHA-256.

For other MCP clients: this package does not install Puppeteer, so a plain npx @pinepaper.studio/mcp-server has no browser, and every tool returns the code it would run instead of running it (the result says so). To execute in a real browser, install Puppeteer in the same npx call. A separate npm i puppeteer in your project is not visible to npx's copy of the server:

{
  "mcpServers": {
    "pinepaper": {
      "command": "npx",
      "args": ["-y", "-p", "puppeteer", "-p", "@pinepaper.studio/mcp-server", "pinepaper-mcp"]
    }
  }
}

Security switches: off by default. Two capabilities are a security boundary and stay off until you, the person running the server, turn them on. An agent cannot turn them on from a tool call.

Switch	Turns on
PINEPAPER_ALLOW_CODE=1	Running JavaScript the agent writes: pinepaper_execute_custom_code, pinepaper_p5_draw, pinepaper_render_hook (register), pinepaper_register_custom_relation, and the custom relations saved in a scene file (pinepaper_import_scene registerCustomRelations).
PINEPAPER_ALLOW_LOCAL_FILES=1	Importing images, audio, video and scenes from your disk (the working folder and PINEPAPER_ASSET_DIRS). URLs and the export folder always work.

With a switch off, those calls are refused with the switch named, and everything else works. Turn one on only if you trust what your agent reads, since a web page or a scene file can steer what it writes. In the Claude Desktop extension they are the "Allow custom code" and "Allow local files" settings. In a config file, add them to the server's env:

"env": { "PINEPAPER_ALLOW_CODE": "1", "PINEPAPER_ALLOW_LOCAL_FILES": "1" }

For code-only use (no Chrome, no 320 MB download), use "args": ["-y", "@pinepaper.studio/mcp-server"] and set "env": { "PINEPAPER_EXECUTION_MODE": "code" }. A global install works too: npm i -g @pinepaper.studio/mcp-server puppeteer, then "command": "pinepaper-mcp".

Made with tool calls

Every graphic below is an animated SVG produced through this server's tool surface — the arguments shown with each result are what an AI agent passes to the named tool. They aren't shell commands; Run these yourself below shows the three ways to execute them.

// The scene IS a graph: two items, two declared edges —
// the canvas view and the graph view are the same data.
{ "sourceId": "$dot",
  "relationType": "moves_along_path",
  "relationOptions": { "path": "$p1",   // an ellipse path
    "duration": 6, "easing": "easeInOut", "loop": true } }
{ "itemId": "$square", "animationType": "rotate",
  "options": { "speed": 0.18 } }

// Five rails, five named easings, one loop — each dot is
// a moves_along_path down its rail with a different easing
for (const easing of ['linear', 'easeIn', 'easeOut',
                      'easeInOut', 'pingpong']) {
  add_relation($dot, 'moves_along_path', {
    equation: { kind: 'parametric', xExpr: '0', yExpr: 't',
                min: -1, max: 1, scale: 58 },
    duration: 2.6, easing, loop: true });
}

// The engine solves the curve; the exporter bakes the
// motion to native SVG keyframes. pinepaper_add_relation:
{ "sourceId": "$dot", "relationType": "moves_along_path",
  "relationOptions": { "equation": {
    "kind": "parametric",
    "xExpr": "cos(2*t)*cos(t)",
    "yExpr": "cos(2*t)*sin(t)",
    "scale": 108, "cx": 280, "cy": 118 },
    "duration": 8, "loop": true } }

// Status chip: pale panel, slate bar, green dot blinking
{ "itemType": "rectangle", "properties": { "width": 264,
  "height": 72, "fillColor": "#e8eff5" } }
{ "itemType": "circle", "properties": { "radius": 9,
  "fillColor": "#2e9b4e" } }
{ "itemId": "$1", "animationType": "fade",
  "options": { "speed": 1.0 } }   // only the dot blinks

All five showcase files (including the banner) live in assets/ — tiny (4–11 KB), dependency-free, loop forever, and render anywhere SVG renders: GitHub READMEs, docs sites, dashboards, emails that allow SVG. They follow one editorial design system (serif mastheads, hairline rules, slate ink on paper white, framed canvas stages, typed-edge graph diagrams) supplied to the agent as context — share a design guideline with your agent and the tool calls come out on-system.

Try it interactive

GitHub can't run scripts inside a README, so the interactive demos live in the editor — one click, no install. Each is a shipped template where the relation graph does all the state handling (tabs, accordions, menus — no event-handler code):

• Tabs from relations — on_click_fire + exclusive_group + on_enter_set_visibility
• Accordion from relations — disclosure pairs via on_event_toggle
• Solar system, 4-in-1 tabs — the state machine driving four scenes
• Menubar from relations — WAI-ARIA menubar semantics from the same graph

The same graph drives visuals, keyboard access, and screen-reader roles (WCAG 2.1 AA) — see pinepaper://docs/relations from your MCP client.

Run these yourself

The snippets above are MCP tool-call arguments — they execute when an AI agent invokes the tool. Three ways to make that happen:

1 · Ask your agent (any MCP client). With this server configured, paste a prompt like:

Create a blue circle and make it ride a diamond-shaped path with easeInOut, looping. Add an orange rotating square beside it. Then export the scene as animated SVG.

Your agent picks the tools (pinepaper_create_item, pinepaper_add_relation, pinepaper_export_svg) and runs them.

2 · Hand your agent a complete batch. This is a full, valid pinepaper_agent_batch_execute argument — an agent (or an MCP inspector) can execute it verbatim; $0/$1 reference the created items in order:

{
  "operations": [
    { "type": "create", "itemType": "circle",
      "properties": { "x": 300, "y": 260, "radius": 10, "fillColor": "#2e5e8f" } },
    { "type": "relation", "relationType": "moves_along_path", "sourceId": "$0",
      "relationOptions": { "path": [ { "x": 180, "y": 260 }, { "x": 300, "y": 180 },
                                     { "x": 420, "y": 260 }, { "x": 300, "y": 340 } ],
                           "duration": 6, "easing": "easeInOut", "loop": true } },
    { "type": "create", "itemType": "rectangle",
      "properties": { "x": 520, "y": 260, "width": 60, "height": 60, "fillColor": "#f0a030" } },
    { "type": "animate", "itemId": "$1", "animationType": "rotate" }
  ]
}

3 · No MCP, no agent — just a browser. Open pinepaper.studio/editor, open the browser console, and paste (verified working as-is):

const app = window.PinePaper;
const dot = app.create('circle', { x: 300, y: 260, radius: 10, fillColor: '#2e5e8f' });
app.addRelation(dot.data.id, null, 'moves_along_path', {
  path: [ {x:180,y:260}, {x:300,y:180}, {x:420,y:260}, {x:300,y:340} ],
  duration: 6, easing: 'easeInOut', loop: true,
});
const sq = app.create('rectangle', { x: 520, y: 260, width: 60, height: 60, fillColor: '#f0a030' });
app.animate(sq, { animationType: 'rotate' });

The same code an agent generates is the code you can paste — the canvas is yours either way, undo included.

Security: yes, it executes code

Supply-chain scanners flag this package, and they are not wrong about the mechanism. Socket and tools like it mark it as malware-adjacent because it evaluates JavaScript at runtime. The detection is correct about the capability and wrong about the intent, so here is exactly what happens.

Every tool emits JavaScript — that is the architecture, not an exception. A tool call is compiled into a snippet written against the PinePaper and Paper.js APIs; the snippet is the product. pinepaper_execute_custom_code is simply the case where the agent writes the snippet instead of the server generating it, which is what lets a model draw something no other tool has a name for. Removing execution would not harden this package, it would delete it.

Code the agent writes is off unless you turn it on. The tools that run JavaScript the agent wrote (pinepaper_execute_custom_code, pinepaper_p5_draw, pinepaper_render_hook register, pinepaper_register_custom_relation, and pinepaper_import_scene's registerCustomRelations) refuse, naming the switch, unless the server is started with PINEPAPER_ALLOW_CODE=1. Reading files from your disk for an import (images, audio, video, scenes) needs PINEPAPER_ALLOW_LOCAL_FILES=1; files in the export folder, the server's own results, are always readable. In the Claude Desktop extension both are settings, off by default. An agent takes instructions from whatever it reads, a web page or a scene file included, so whether that text may become code is the decision of whoever starts the server.

Where the code runs. In a browser page on your own machine, against your own canvas. It does not run in the server process, and nothing is sent anywhere else to be executed.

Two modes, and one of them never executes anything:

Mode	What happens
code (PINEPAPER_EXECUTION_MODE=code)	The tool returns the JavaScript and stops. Nothing runs. You read it and paste it if you want it.
puppeteer (default)	The server launches Chrome and runs the snippet in the page via page.evaluate().

If you do not want an agent executing anything, code mode is a first-class path, not a degraded one — the same snippet, handed to you instead of run.

What guards execution. On current engine builds the snippet goes through app.runGenerated(code, { source: 'agent' }) — a governor with seeded determinism, loop and item budgets, and a machine-readable report — rather than a bare eval. Older engine builds fall back to eval.

Found a vulnerability? Report it privately, as SECURITY.md describes, not in a public issue.

What to weigh before running it.

• Code an agent writes runs with whatever that browser page has. Give this server the same trust you would give anything else you let write and run code on your machine — which is the trust you already extend to an MCP client with tool access.
• Puppeteer mode launches Chrome with --no-sandbox and --disable-setuid-sandbox. That is routine for headless automation and it does weaken Chrome's own process sandbox. If that matters where you are running it, use code mode or put the server in a container.
• Puppeteer itself is not a dependency at all (it was an optional peer until 1.6.25), kept out of the tree precisely because a headless browser plus an install script is what scanners flag hardest. Install it only if you want the executing mode. The server loads it only from where its own dependencies would be found (the same npx call, a global install, a project install) or from a folder you name in PINEPAPER_PUPPETEER_FROM; never from the folder it happens to be started in. puppeteer 22 or newer is required.
• The npm package starts no process. Two export features use ffprobe and ffmpeg: checking a saved video against what the studio encoded, and joining the cached segments of a perScene export (ffmpeg -f concat). Only the Claude Desktop extension runs them, through a small runner it bundles that allows those two binaries alone, via execFile (no shell, argument lists the server writes, absolute paths). From npm, the check is skipped and said so, and a perScene export runs whole.
• The server itself fetches the images, SVGs and media a tool call names by URL, and reads local files named by path. URLs that resolve to loopback, private, link-local or reserved addresses are refused, redirects included, and so are cloud metadata addresses. Local files are read only with PINEPAPER_ALLOW_LOCAL_FILES=1, and then only from the working directory, the export folder, and folders listed in PINEPAPER_ASSET_DIRS (the export folder is readable without the switch). PINEPAPER_ALLOW_PRIVATE_NETWORK=1 allows local and LAN hosts. Metadata addresses stay refused even with it set.

What's new in 1.6.35

Fixed

• A batch relation op with a name pattern (sourceId: "disc-*") binds phase_wave, ring_forming and flock once over every match, so each member gets its own phase, ring slot or boid. It used to bind one relation per item, and every member took the first slot. ring_forming with no center or target centres on the members.
• A PDF still honours time while the timeline is playing.
• A PDF with bleed on a named paper size no longer warns that the bleed was dropped: it is applied (the page is the sheet plus the bleed). The warning now covers trim marks only, and only when the studio didn't draw them. The result's print record, where the studio sends one, says what the page carries.
• An export region whose output has a different shape is cropped about its centre. It used to draw content from outside the region, and black past the canvas edge. The reply's croppedTo says what was rendered.
• A GIF with maxBytes reports the size of the file it delivers, read from the file, and never delivers a retry larger than the first file.
• morph_sequence takes every easing the studio names, including back and elastic.
• on_complete and at_beat with an event's name in params.event fire that event. The name is resolved to the event's id (the reply's eventResolvedTo); a name two events share is named in a warning. It used to bind without a word and never fire.
• visible: false on create (and in a batch create) hides the item. It was reported as ignored and the item was drawn.
• A refused export carries the studio's reason as cause (for example audio_codec_unavailable) under the error code EXPORT_FAILED.

Changed

• Relation params a relation does not read are now named for the long-form relations too (then, after, phase_wave, ring_forming, flock, on_complete, at_beat, camera_tracks, soundtrack_cue), against the params the current studio declares.
• add_contraption warns when sourceEvent is an event's name and the studio kept it as a literal channel: a timed event and a pulse fire the event's id, so pass the eventId that create returned. A studio that resolves the name says so in sourceEventResolvedTo.
• An emitter fade other than none, linear or { in, out } is named in a warning.
• The relation docs say what on_complete, at_beat and triggers_animation do: reveal a hidden target and pulse an event. They don't re-time a track; use then. A rule's fireCount is put back after an export, like everything else the rule changed.

What's new in 1.6.34

Added

• keys on keyframe_animate sends a track by column instead of one object per key: {"time":[0,1,2],"x":[100,400,700],"easing":"easeOut"}. Evenly spaced keys can use "time":{"step":0.033333,"count":180}. A 180-key track of x and y is about three times smaller to send, or four with even spacing, and renders the same.
• create_many in pinepaper_agent_batch_execute makes many items of one type, with what they share stated once. 300 items sharing five properties are about fifteen times smaller to send.
• PINEPAPER_TOOLKIT=starter serves five tools, enough for a first scene: the batch, keyframes, patterns, export and lint. The eight-tool lane adds events, starting over and custom relations.