Which integrations are available for this server?

Enables creation and animation of graphics in PinePaper Studio, with the ability to export animated SVG files and generate procedural backgrounds, shapes, and text with behavior-driven relations.

How do I use PinePaper MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PinePaper MCP Server create a flowchart for our user login process" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

PinePaper MCP Server

Create animated graphics with AI using the Model Context Protocol

npm version License: MIT

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.). Using natural language, you can:

Create text, shapes, and complex graphics
Animate items with behavior-driven relations
Generate procedural backgrounds
Export animated SVG and training data

Quick Start

1. Install

# Using npm npm install -g @pinepaper.studio/mcp-server # Using bun bun add -g @pinepaper.studio/mcp-server

2. Configure Your AI Client

Add to your MCP client configuration. Examples:

Claude Desktop (claude_desktop_config.json):

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

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

Other MCP Clients: Refer to your AI client's MCP configuration documentation.

3. Start Using

Open your AI client and try:

"Create a red pulsing text that says HELLO"

"Create a sun and earth, make earth orbit the sun"

"Add a sunburst background with blue and purple colors"

Features

📐 Diagram Tools (NEW in v1.4.3)

Create flowcharts, UML diagrams, network diagrams, and more:

"Create a flowchart for user login process" "Make a UML class diagram for the User class" "Design a network topology with 3 servers connected to a cloud"

Shape Types:

Flowchart: process, decision, terminal, data, document, database, preparation
UML: uml-class, uml-usecase, uml-actor
Network: cloud, server
Basic: rectangle, circle, triangle, star

Connector Features:

Smart routing (orthogonal, direct, curved)
Arrow styles (classic, stealth, diamond, circle, none)
Animated bolt effect for data flow
Labels on connectors

Auto-Layout Algorithms:

Hierarchical (flowcharts, org charts)
Force-directed (network diagrams)
Tree (hierarchies)
Radial (mind maps)
Grid (component libraries)

Tools:

pinepaper_create_diagram_shape - Create diagram shapes with ports
pinepaper_connect - Connect items with smart connectors
pinepaper_connect_ports - Connect specific ports
pinepaper_add_ports - Add connection ports to items
pinepaper_auto_layout - Automatically arrange items
pinepaper_get_diagram_shapes - List available shapes
pinepaper_update_connector - Update connector properties
pinepaper_remove_connector - Remove a connector
pinepaper_diagram_mode - Control diagram editing mode

🔍 Asset Search & Import (NEW in v1.3.0)

Search and import free SVG assets from multiple repositories:

"Search for a rocket icon" "Import a cat illustration" "Add a user avatar icon"

Supported Repositories:

SVGRepo: 500,000+ icons with various licenses
OpenClipart: 150,000+ public domain clipart (CC0)
Iconify: 200,000+ icons from multiple icon sets
Font Awesome: 2,000+ free icons (CC BY 4.0)

Tools:

pinepaper_search_assets - Search across all repositories
pinepaper_import_asset - Import and place on canvas

📊 Performance Metrics (NEW in v1.3.0)

Built-in performance tracking helps AI assistants optimize workflows:

Automatic timing for all tool operations
Phase breakdown (validation, code generation, execution, screenshots)
Export formats: summary, detailed JSON, CSV
Self-optimization through pinepaper_get_performance_metrics

Example workflow:

1. Run your scene creation workflow 2. Call pinepaper_get_performance_metrics 3. Identify bottlenecks (e.g., individual creates vs batch) 4. Adjust approach and re-run

🐛 Enhanced Error Messages (NEW in v1.3.0)

Errors now include canvas context for easier debugging:

Total item count and types
Active relations
Recent items created
Canvas state at time of error

Makes troubleshooting much faster and more precise.

🎨 Item Creation

Create text, shapes, and custom graphics:

"Create a blue circle at position 200, 300 with radius 50" "Add a gold star in the center" "Create text saying 'Welcome' with font size 72"

🔄 Relations (Behavior-Driven Animation)

The key feature - describe HOW items should behave:

Relation	Description	Example
`orbits`	Circular motion	"Moon orbits Earth"
`follows`	Move toward target	"Label follows player"
`attached_to`	Fixed offset	"Hat attached to character"
`maintains_distance`	Stay at distance	"Satellite 200px from station"
`points_at`	Face target	"Arrow points at target"
`mirrors`	Mirror position	"Reflection mirrors original"
`parallax`	Depth movement	"Background parallax scroll"
`bounds_to`	Stay within area	"Player stays in arena"

🎬 Simple Animations

For quick looping effects:

pulse - Scale up/down
rotate - Continuous spin
bounce - Vertical bounce
fade - Opacity cycle
wobble - Side-to-side
slide - Horizontal slide
typewriter - Character reveal

🖼️ Background Generators

Procedural patterns:

drawSunburst - Radial rays
drawSunsetScene - Animated sunset
drawGrid - Lines, dots, squares
drawWaves - Layered waves
drawCircuit - Tech circuit board

📊 Training Data Export

Generate instruction/code pairs for LLM fine-tuning:

"Export training data from this scene"

Outputs pairs like:

{ "instruction": "moon orbits earth at radius 100", "code": "app.addRelation('item_1', 'item_2', 'orbits', {radius: 100})" }

Tools Reference

Item Tools

Tool	Description
`pinepaper_create_item`	Create text, shapes, graphics
`pinepaper_modify_item`	Change item properties
`pinepaper_delete_item`	Remove an item
`pinepaper_batch_create`	Create multiple items at once
`pinepaper_batch_modify`	Modify multiple items at once
`pinepaper_create_grid`	Create items in a grid layout
`pinepaper_create_glossy_sphere`	Create 3D glossy sphere effect
`pinepaper_create_diagonal_stripes`	Create diagonal stripe pattern

Relation Tools

Tool	Description
`pinepaper_add_relation`	Create behavioral relationship
`pinepaper_remove_relation`	Remove relationship
`pinepaper_query_relations`	Find existing relations

Animation Tools

Tool	Description
`pinepaper_animate`	Apply simple loop animation
`pinepaper_keyframe_animate`	Timed keyframe animation
`pinepaper_play_timeline`	Control playback

Generator Tools

Tool	Description
`pinepaper_execute_generator`	Run background generator
`pinepaper_list_generators`	List available generators

Effect Tools

Tool	Description
`pinepaper_apply_effect`	Apply sparkle, blast effects

Asset Tools (NEW)

Tool	Description
`pinepaper_search_assets`	Search for SVG assets across repositories
`pinepaper_import_asset`	Import asset from search results

Query Tools

Tool	Description
`pinepaper_get_items`	Get canvas items
`pinepaper_get_relation_stats`	Relation statistics
`pinepaper_get_performance_metrics`	Get execution timing metrics

Diagram Tools (NEW in v1.4.3)

Tool	Description
`pinepaper_create_diagram_shape`	Create flowchart/UML/network shapes with ports
`pinepaper_connect`	Connect items with smart connectors
`pinepaper_connect_ports`	Connect specific ports on items
`pinepaper_add_ports`	Add connection ports to items
`pinepaper_auto_layout`	Auto-arrange items using layout algorithms
`pinepaper_get_diagram_shapes`	List available diagram shapes
`pinepaper_update_connector`	Update connector style/label
`pinepaper_remove_connector`	Remove a connector
`pinepaper_diagram_mode`	Control diagram editing mode

Canvas Tools

Tool	Description
`pinepaper_set_background_color`	Set background
`pinepaper_set_canvas_size`	Set dimensions

Export Tools

Tool	Description
`pinepaper_export_svg`	Export animated SVG
`pinepaper_export_training_data`	Export LLM training pairs

Examples

Solar System

1. Create a yellow circle as the sun (radius 60) at center 2. Create a blue circle as Earth (radius 20) 3. Create a gray circle as the Moon (radius 8) 4. Add relation: Earth orbits Sun at radius 150, speed 0.3 5. Add relation: Moon orbits Earth at radius 40, speed 0.8

Animated Logo

1. Create text "BRAND" with font size 96 2. Apply pulse animation with speed 0.5 3. Apply sparkle effect with gold color 4. Add sunburst background

Following Labels

1. Create a circle as "player" 2. Create text "Player 1" as the label 3. Add relation: label follows player with offset [0, -50]

Flowchart Diagram (NEW)

1. Create a terminal shape with label "Start" 2. Create a process shape with label "Get Input" 3. Create a decision shape with label "Valid?" 4. Create a terminal shape with label "End" 5. Connect Start → Get Input 6. Connect Get Input → Valid? 7. Connect Valid? → End (label: "Yes") 8. Connect Valid? → Get Input (label: "No", routing: curved) 9. Apply hierarchical auto-layout

Network Diagram (NEW)

1. Create a cloud shape with label "Internet" 2. Create 3 server shapes with labels "Web", "API", "DB" 3. Connect Internet → Web (label: "HTTPS") 4. Connect Web → API (label: "REST") 5. Connect API → DB (label: "SQL") 6. Apply force-directed auto-layout

Architecture

┌─────────────────────────────────────────────────────────────┐ │ AI Client (Claude, etc.) │ │ │ │ │ MCP Protocol │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ PinePaper MCP Server │ │ │ │ ┌─────────────────┐ │ │ │ │ │ Tool Handlers │ │ │ │ │ └────────┬────────┘ │ │ │ │ │ │ │ │ │ ┌────────▼────────┐ │ │ │ │ │ Code Generator │ │ │ │ │ └────────┬────────┘ │ │ │ └───────────┼───────────┘ │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ PinePaper Studio │ │ │ │ (Browser/App) │ │ │ └───────────────────────┘ │ └─────────────────────────────────────────────────────────────┘

Development

Setup

git clone https://github.com/pinepaper/mcp-server.git cd mcp-server # Using npm npm install npm run build # Using bun (recommended) bun install bun run build

Test with MCP Client (Local)

Build the server:
# Using npm npm run build # Using bun bun run build
Add to your MCP client config (example for Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):
{ "mcpServers": { "pinepaper": { "command": "node", "args": ["/full/path/to/mcp-server/dist/cli.js"] } } }
Restart your MCP client
Test with: "What PinePaper tools do you have available?"

Run Tests

# Using npm npm test # Using bun bun test # Run with coverage bun test --coverage

Development Watch Mode

# Using npm npm run dev # Using bun bun run dev

Internationalization (i18n)

PinePaper MCP Server supports 51 languages, providing localized tool descriptions and messages for AI agents.

Supported Languages

Category	Languages
European	English, Spanish, French, German, Italian, Portuguese (+ Brazilian), Dutch, Polish, Russian, Ukrainian, Swedish, Danish, Norwegian, Finnish, Czech, Greek, Hungarian, Romanian, Turkish, Icelandic
East Asian	Chinese (Simplified & Traditional), Japanese, Korean
Southeast Asian	Thai, Vietnamese, Indonesian, Malay, Tagalog, Filipino
South Asian	Hindi, Bengali, Tamil, Telugu, Marathi, Gujarati, Kannada, Malayalam, Punjabi, Urdu
Middle Eastern	Arabic, Hebrew, Persian (RTL support)
Indigenous (Canada)	Chipewyan, Cree, Michif, Inuktitut, Mi'kmaq, Mohawk, Ojibwe

How It Works

The i18n system provides localized:

Tool names and descriptions
Error messages
Success messages
UI labels for item types, relations, animations, and generators

Setting Language

Set the PINEPAPER_LOCALE environment variable:

# In MCP client config (example for Claude Desktop) { "mcpServers": { "pinepaper": { "command": "npx", "args": ["-y", "@pinepaper.studio/mcp-server"], "env": { "PINEPAPER_LOCALE": "ja" } } } }

Or programmatically:

import { setLocale, t } from '@pinepaper.studio/mcp-server'; // Set locale setLocale('fr'); // Get translated string const description = t('tools.pinepaper_create_item.description');

Adding New Languages

Create a new locale file in src/i18n/locales/ (e.g., xx.ts)
Copy the structure from en.ts
Translate all strings
Export from src/i18n/locales/index.ts
Add to the localeMap

See CONTRIBUTING.md for detailed guidelines.

Configuration

Environment Variables

Variable	Description	Default
`PINEPAPER_DEBUG`	Enable debug logging	`false`
`PINEPAPER_LOG_LEVEL`	Log level (error/warn/info/debug)	`info`
`PINEPAPER_LOCALE`	Language locale code	`en`
`PINEPAPER_METRICS_ENABLED`	Enable performance metrics tracking	`true`
`PINEPAPER_METRICS_RETENTION`	Max metrics to retain in memory	`1000`
`PINEPAPER_SCREENSHOT_MODE`	Screenshot mode (on_request/always/never)	`on_request`

Performance Metrics

PinePaper MCP Server includes built-in performance tracking to help AI assistants optimize workflows by identifying bottlenecks and choosing faster alternatives.

Key Features:

⚡ Automatic timing for all tool operations
📊 Phase breakdown (validation, code generation, browser execution, screenshots)
🎯 Real-time query via pinepaper_get_performance_metrics tool
📈 Export formats: summary, JSON, CSV
💾 In-memory storage (resets on restart)
🚀 Minimal overhead (~1ms per operation)

Quick Example:

AI: "Let me check if batch operations are faster" → pinepaper_get_performance_metrics(format: 'summary') Result: - pinepaper_create_item: avg 145ms - pinepaper_batch_create (10 items): avg 298ms (~30ms per item) AI: "I'll use batch_create for the next 20 items"

Configuration:

# Disable metrics if not needed export PINEPAPER_METRICS_ENABLED=false # Increase retention for long sessions export PINEPAPER_METRICS_RETENTION=5000

Learn More: See docs/PERFORMANCE_METRICS.md for complete documentation.

Documentation

Guides

Workflow Guide - Decision trees, multi-step patterns, performance optimization, and troubleshooting
Performance Metrics - In-memory metrics system for AI self-optimization
PinePaper Reference - Complete PinePaper Studio API reference

External Documentation

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Run tests: npm test
Submit a pull request

License

MIT License - see LICENSE for details.

Support

📧 Email: support@pinepaper.studio
🐛 Issues: GitHub Issues

Made with ❤️ by the PinePaper team