PinePaper MCP Server
Create animated graphics with AI using the Model Context Protocol
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 portspinepaper_connect- Connect items with smart connectorspinepaper_connect_ports- Connect specific portspinepaper_add_ports- Add connection ports to itemspinepaper_auto_layout- Automatically arrange itemspinepaper_get_diagram_shapes- List available shapespinepaper_update_connector- Update connector propertiespinepaper_remove_connector- Remove a connectorpinepaper_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 repositoriespinepaper_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/downrotate- Continuous spinbounce- Vertical bouncefade- Opacity cyclewobble- Side-to-sideslide- Horizontal slidetypewriter- Character reveal
🖼️ Background Generators
Procedural patterns:
drawSunburst- Radial raysdrawSunsetScene- Animated sunsetdrawGrid- Lines, dots, squaresdrawWaves- Layered wavesdrawCircuit- 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_metricstool - 📈 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.
Links
Support
- 📧 Email: support@pinepaper.studio
- 🐛 Issues: GitHub Issues
Made with ❤️ by the PinePaper team