Canvelete MCP Server
Model Context Protocol (MCP) server for the Canvelete design platform. This server exposes Canvelete's design capabilities to AI assistants and other MCP-compatible clients, enabling programmatic design creation and manipulation.
🔗 Links:
- Canvelete Platform - Create designs online
- Documentation - Full API and platform documentation
- Get API Key - Generate your API key
📚 MCP Server Documentation:
- Element Types Guide - Complete guide to all 13 element types (including QR codes & barcodes), their capabilities, and styling limits
- Asset Search Guide - How to search and use external assets (Pixabay, Unsplash, Iconify, cliparts, illustrations)
- Examples - Practical examples and use cases
- MCP Setup Guide - Configuration and usage instructions
Quick Start
# Install globally
npm install -g @canveletedotcom/mcp-server
# Or use with npx (no installation needed)
npx -y @canveletedotcom/mcp-server start
Then configure your MCP client (Claude Desktop, Kiro, etc.) with:
{
"mcpServers": {
"canvelete-mcp-server": {
"command": "canvelete-mcp",
"args": ["start"],
"env": {
"CANVELETE_API_KEY": "your_api_key_here"
}
}
}
}
Features
Resources (Read-Only Data Access)
- Designs: Access user designs, browse templates
- Canvas: View canvas state and elements
- Assets: Browse user's asset library and available fonts
- User: Access profile and preferences
- Metadata: Complete element capabilities, styling limits, and design system documentation
Tools (Actions)
- Design Management: Create, update, delete, duplicate, and export designs
- Canvas Manipulation: Add, update, delete elements; resize canvas; clear canvas
- 13 Element Types: rectangle, circle, text, image, svg, line, polygon, star, qr, barcode, table, container, bezier
- QR Codes: Generate QR codes for URLs, vCards, WiFi, and more
- Barcodes: Support for CODE128, EAN13, UPC, and 7 other formats
- Templates: List, apply, and create templates
- Assets: Comprehensive asset search across multiple sources
- Pixabay: 2.7M+ free stock photos and illustrations
- Unsplash: 3M+ high-quality curated photos
- Iconify: 200K+ icons from 150+ icon sets
- Cliparts: 10K+ curated clipart graphics
- Illustrations: 5K+ artistic illustrations
- Fonts: 30+ professional fonts with metadata and pairing recommendations
- Shapes: 70+ SVG shapes from 8 categories (basic, arrows, stars, callouts, nature, symbols, geometric, extra)
- AI Integration: Access Civi AI for design generation
Available Prompts
Prompts provide guided templates for common design tasks:
create_social_post- Create social media posts (Instagram, Facebook, Twitter, etc.)create_presentation_slide- Create presentation slides with title and contentadd_text_element- Add styled text elements to designs
Prompts help AI assistants create designs with proper structure and styling automatically.
Installation
Method 1: Global Installation (Recommended)
Install the package globally to use the canvelete-mcp command:
npm install -g @canveletedotcom/mcp-server
Method 2: NPX (No Installation Required)
Use npx to run without installing:
npx -y @canveletedotcom/mcp-server start
Method 3: Local Development
For development or custom builds:
git clone https://github.com/canvelete/canvelete.git
cd canvelete/mcp-server
npm install
npm run build
Then use the local build path in your MCP configuration.
Configuration
Environment Variables
Create a .env file in the mcp-server directory:
# Required: Canvelete API Key
CANVELETE_API_KEY =your_api_key_here
# Optional: Canvelete API URL (defaults to https://www.canvelete.com)
CANVELETE_API_URL=https://www.canvelete.com
# Optional: For AI generation features (if using Civi AI directly)
GEMINI_API_KEY=your_gemini_api_key
Authentication
You need a Canvelete API key to use the MCP server:
- Log in to your Canvelete account
- Go to Settings → API Keys
- Generate a new API key
- Save the key securely
For detailed API documentation, see docs.canvelete.com.
You can provide the API key in two ways:
Option 1: Environment Variable (recommended for Claude Desktop)
CANVELETE_API_KEY=your_api_key_here
Option 2: Tool Arguments (for programmatic use)
{
"apiKey": "your_api_key_here",
"name": "My Design"
}
Configuration
Claude Desktop
-
Find your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- macOS:
-
Add the Canvelete server configuration:
Option A: Using Global Installation
{
"mcpServers": {
"canvelete-mcp-server": {
"command": "canvelete-mcp",
"args": ["start"],
"env": {
"CANVELETE_API_KEY": "your_api_key_here",
"CANVELETE_API_URL": "https://www.canvelete.com"
}
}
}
}
Option B: Using NPX (No Installation)
{
"mcpServers": {
"canvelete-mcp-server": {
"command": "npx",
"args": ["-y", "@canveletedotcom/mcp-server", "start"],
"env": {
"CANVELETE_API_KEY": "your_api_key_here",
"CANVELETE_API_URL": "https://www.canvelete.com"
}
}
}
}
Option C: Using Local Build
{
"mcpServers": {
"canvelete-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.cjs", "start"],
"env": {
"CANVELETE_API_KEY": "your_api_key_here",
"CANVELETE_API_URL": "https://www.canvelete.com"
}
}
}
}
- Restart Claude Desktop
Kiro
-
Find your Kiro config file:
~/.kiro/settings/mcp.json -
Add the same configuration as above
-
Restart Kiro
Other MCP Clients
Any MCP-compatible client can use this server. Configure it to run:
- Command:
canvelete-mcp(if installed globally) ornpx -y @canveletedotcom/mcp-server - Args:
["start"] - Environment: Set
CANVELETE_API_KEYand optionallyCANVELETE_API_URL
Usage Examples
Example Conversations
Once configured, you can ask your AI assistant:
- "What designs do I have in Canvelete?"
- "Create a new 1080x1080 Instagram post design called 'Summer Sale'"
- "Add a text element to design {id} that says 'Hello World'"
- "Export design {id} as PNG"
- "List all my uploaded assets"
- "Apply template {template-id} to design {design-id}"
- "Create a presentation slide with title 'Welcome' and subtitle 'Introduction'"
- "Search for stock images of mountains"
Quick Example: Create a Social Media Post
// 1. Create a design
create_design({
name: "Summer Sale Post",
width: 1080,
height: 1080
})
// 2. Add background
add_element({
designId: "{design-id}",
element: {
type: "rectangle",
x: 0, y: 0,
width: 1080, height: 1080,
fill: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
}
})
// 3. Add text
add_element({
designId: "{design-id}",
element: {
type: "text",
text: "SUMMER SALE",
x: 100, y: 400,
width: 880, height: 150,
fontSize: 96,
fontFamily: "Poppins",
fill: "#FFFFFF",
fontWeight: "bold"
}
})
// 4. Export
export_design({
designId: "{design-id}",
format: "png",
quality: 100
})
See EXAMPLES.md for more detailed examples. For complete API documentation, visit docs.canvelete.com.
Available Resources
Resources provide read-only access to Canvelete data:
| URI | Description |
|---|---|
canvelete://api/designs/list | List all user's designs with pagination |
canvelete://api/designs/templates | Browse public design templates |
canvelete://api/design/{id} | Get detailed information about a specific design |
canvelete://api/canvas/{designId} | Get the current canvas state for a design |
canvelete://api/canvas/{designId}/elements | Get all elements on a design canvas |
canvelete://api/assets/library | User's uploaded assets (images, fonts, etc.) |
canvelete://api/assets/fonts | List of all available fonts for text elements |
canvelete://api/user/profile | User profile and subscription information |
canvelete://api/user/preferences | User editor preferences and settings |
canvelete://api/metadata/schema | System metadata, schemas, and property definitions |
Available Tools
Design Management Tools
list_designs- List all user's designs with pagination and searchget_design- Get detailed design info including canvas datacreate_design- Create new design with custom dimensionsupdate_design- Update design properties (name, description, visibility)delete_design- Delete a design permanentlyduplicate_design- Fork/copy an existing designexport_design- Export design to PNG, JPG, PDF, or SVG format
Canvas Manipulation Tools
add_element- Add any element type (shape, text, image, SVG, etc.)update_element- Modify element properties (position, style, content)delete_element- Remove an element from canvasresize_canvas- Change canvas dimensionsclear_canvas- Remove all elements from canvas
Template Tools
list_templates- Browse available design templatesapply_template- Apply a template to an existing designcreate_template- Save a design as a reusable template
Asset Management Tools
list_assets- View user's asset library (images, fonts, etc.)search_stock_images- Search Pixabay for stock imagessearch_icons- Search for icon assetssearch_clipart- Search for clipart imagessearch_illustrations- Search for illustration assetslist_fonts- List available fonts by categoryupload_asset- Upload a new asset to the library
AI Tools
generate_design- Generate designs using AIchat_with_civi- Interact with Civi AI for design assistance
Element Types
Supported canvas element types:
- rectangle - Rectangular shapes
- circle - Circular/elliptical shapes
- text - Text elements with fonts
- image - Images from URLs or assets
- line - Straight lines
- polygon - Multi-sided shapes
- star - Star shapes
- svg - SVG graphics
- bezier - Curved paths
- container - Group elements
- table - Data tables
Development
Build
npm run build
Run in Development
npm run dev
Type Check
npm run type-check
Clean Build
npm run clean
npm run build
MCP Protocol Compliance
This server follows the MCP Protocol specification (2025-11-25).
Compliance Documentation:
- MCP_COMPLIANCE.md - Implementation best practices and protocol compliance
- SPECIFICATION_COMPLIANCE.md - Detailed compliance with official MCP specification (2025-11-25)
Key Compliance Features:
- ✅ All logging uses stderr (never stdout) to avoid corrupting JSON-RPC messages
- ✅ Proper error handling and formatting
- ✅ Complete tool, resource, and prompt definitions
- ✅ Standard MCP server structure and initialization
Testing Compliance:
# Use MCP Inspector to verify compliance
npx @modelcontextprotocol/inspector canvelete-mcp start
Troubleshooting
"Invalid API key"
- Generate a new API key in Canvelete Settings → API Keys
- Verify the key is set correctly in your MCP config
- Check key hasn't expired or been revoked
- Run the test script to verify:
npx tsx test-auth.ts your_api_key
"Permission denied"
- Ensure API key has appropriate scopes
- Verify you own the resource you're modifying
"Failed to connect to API"
- Check
CANVELETE_API_URLis correct (default: https://www.canvelete.com) - Verify network connectivity to the Canvelete API
- For local development, ensure the Canvelete app is running
Claude Desktop doesn't show resources
- Restart Claude Desktop
- Check the config file syntax
- Verify the server path is absolute
- Check stderr logs for errors
Real-time Sync
The MCP server supports real-time synchronization with the design editor via WebSocket. When you make changes through MCP tools, the editor will instantly update to reflect those changes.
Setup
- Start the WebSocket server (in the main Canvelete directory):
pnpm ws
-
The WebSocket server runs on port 3001 by default. You can change this with the
WS_PORTenvironment variable. -
Open the design editor - you'll see a sync indicator in the top-right corner showing connection status.
How it works
- When MCP tools modify a design (add/update/delete elements, resize canvas, etc.), the changes are broadcast via WebSocket
- All connected editor clients subscribed to that design receive instant updates
- The editor shows a "Live" indicator when connected, with a count of received updates
Environment Variables
# WebSocket server port (default: 3001)
WS_PORT=3001
# WebSocket server URL for MCP server to connect to
WS_SERVER_URL=ws://localhost:3001/ws
Security & Privacy
API Key Security
- Never commit API keys to version control or share them publicly
- Use environment variables or secure configuration files
- Rotate keys regularly if compromised or exposed
- Use separate keys for development and production
Data Privacy
- The MCP server accesses your Canvelete account data through API keys
- All API communication uses HTTPS encryption
- API keys have scoped permissions based on your account settings
- Review your API key permissions in Canvelete Settings → API Keys
Rate Limiting
- API keys may have rate limits based on your subscription plan
- The server respects rate limits and will return appropriate errors
- Check your subscription plan for rate limit details
Best Practices
- Only use trusted API keys from your own account
- Don't share your API keys with untrusted parties
- Monitor your API usage in Canvelete dashboard
- Report security issues to security@canvelete.com (do not open public issues)
Deployment Modes
The Canvelete MCP Server supports both local and cloud deployment. See DEPLOYMENT.md for detailed deployment instructions.
Local Deployment (Default)
The server runs locally on your machine using stdio transport, which is the standard for MCP clients like Claude Desktop, Kiro, and Cursor.
Advantages:
- ✅ Full control over your environment
- ✅ No network latency
- ✅ Data stays on your machine
- ✅ Simple setup and configuration
- ✅ Works offline (once API key is cached)
Use Cases:
- Personal development
- Testing and debugging
- Privacy-sensitive workflows
- Desktop applications (Claude Desktop, Cursor, etc.)
Cloud Deployment
The server can be deployed to cloud platforms using containerization or serverless functions. The stdio transport works seamlessly in cloud environments.
Advantages:
- ✅ Scalable and always available
- ✅ No local resource usage
- ✅ Accessible from multiple devices
- ✅ Managed infrastructure
- ✅ Easy updates and maintenance
Supported Platforms:
- Docker/Containers: Deploy to any container platform (Docker, Kubernetes, etc.)
- Google Cloud Run: Serverless container platform
- Azure Functions: Serverless with custom handlers
- AWS Lambda: Serverless functions (with stdio adapter)
- Vercel/Netlify: Serverless platforms
- Any Node.js hosting: Railway, Render, Fly.io, etc.
Quick Cloud Examples:
# Docker deployment (using published package)
docker build -f Dockerfile.simple -t canvelete-mcp-server .
docker run -e CANVELETE_API_KEY=your_key canvelete-mcp-server
# Or use docker-compose
docker-compose up -d
See DEPLOYMENT.md for complete deployment guides for:
- Docker/Containers (Dockerfile included)
- Google Cloud Run
- Azure Functions
- AWS Lambda
- Railway, Render, Fly.io
- Vercel/Netlify
Requirements
- Node.js: >= 18.0.0
- Canvelete Account: Sign up at canvelete.com
- Canvelete API Key: Get one from Canvelete Settings → API Keys
- Documentation: See docs.canvelete.com for API reference
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Quick steps:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
For detailed contribution guidelines, code standards, and development setup, see CONTRIBUTING.md.
Changelog
See CHANGELOG.md for a detailed list of changes and version history.
License
MIT License - see LICENSE file for details.
Support
For issues and questions:
- GitHub Issues: canvelete/canvelete/issues
- Platform Documentation: docs.canvelete.com
- Canvelete Platform: canvelete.com
- API Documentation: docs.canvelete.com/api
- Get Help: Visit canvelete.com/support or docs.canvelete.com/help
Deployment Architecture
How It Works
The MCP server uses stdio transport by default, which works in both local and cloud environments:
- Local Mode: MCP clients (Claude Desktop, etc.) spawn the server process and communicate via stdin/stdout
- Cloud Mode: Cloud platforms run the server in containers/functions and handle stdio communication through their infrastructure
Data Flow
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ MCP Client │ ◄──────► │ MCP Server │ ◄──────► │ Canvelete │
│ (Claude) │ stdio │ (This Server)│ HTTPS │ API │
└─────────────┘ └──────────────┘ └─────────────┘
- MCP Protocol: JSON-RPC over stdio (local) or HTTP/SSE (cloud)
- Canvelete API: Always HTTPS to
https://canvelete.com
Choosing Deployment Mode
Use Local Deployment if:
- You're using Claude Desktop, Cursor, or other desktop MCP clients
- You want maximum privacy and control
- You're developing or testing
- You have a single user/machine
Use Cloud Deployment if:
- You need 24/7 availability
- You want to share access across multiple devices
- You need scalability for multiple users
- You prefer managed infrastructure
Related Links
Canvelete Resources
- Canvelete Platform - Create and edit designs online
- Documentation - Complete platform and API documentation
- API Reference - Detailed API documentation
- Get Started Guide - Platform getting started guide