vestaboard-mcp

v1.0.0

Published

3 months ago

MCP server for Vestaboard API integration with VBML support

Downloads

0High
0Medium
0Low

superadnim

vestaboard mcp api vbml display messaging

🎯 Vestaboard MCP Server

The most complete Model Context Protocol (MCP) server for Vestaboard integration

Transform your Vestaboard into a powerful AI-controlled display with 12 specialized tools, complete VBML support, and seamless integration with Claude, GPT, and any MCP-compatible AI system.

🚀 Why This MCP Server?

✨ Most Complete Vestaboard Integration

12 Tools Total: More than any other Vestaboard MCP implementation
Dual API Support: Both Read/Write API (simple) and Subscription API (advanced)
Full VBML Support: Advanced layouts, positioning, and dynamic content
Utility Functions: Text conversion, validation, board clearing

⚡ Production Ready

Zero Dependencies Issues: Uses stable MCP SDK and node-fetch
Error Handling: Comprehensive validation and helpful error messages
Rate Limit Aware: Built-in warnings for Vestaboard's 15-second limits
Environment Variables: Secure credential management

🎨 AI-Optimized Features

Black Board Optimized: Smart color recommendations for maximum visibility
Text-to-Display: Automatic character code conversion with justification
Board Validation: Pre-flight checks prevent API errors
VBML Composition: Create complex layouts programmatically

📦 Installation

Global Installation (Recommended)

npm install -g vestaboard-mcp

Local Installation

npm install vestaboard-mcp

🔧 Claude Code Integration

Method 1: Read/Write API (Easiest!)

Get a Read/Write key from web.vestaboard.com:

Create an "Installable"
Generate API Credential
Copy Read/Write key

{
  "vestaboard": {
    "command": "npx",
    "args": ["vestaboard-mcp"],
    "env": {
      "VESTABOARD_READ_WRITE_KEY": "your-read-write-key-here"
    }
  }
}

Method 2: Subscription API (Multiple Boards)

For advanced features and multiple boards:

{
  "vestaboard": {
    "command": "npx", 
    "args": ["vestaboard-mcp"],
    "env": {
      "VESTABOARD_API_KEY": "your-api-key-here",
      "VESTABOARD_API_SECRET": "your-api-secret-here"
    }
  }
}

Method 3: Other MCP Clients

Works with any MCP-compatible system:

# Direct execution
npx vestaboard-mcp

# With environment variables
VESTABOARD_READ_WRITE_KEY="your-key" npx vestaboard-mcp

🛠️ Complete Tool Reference

🚀 Read/Write API Tools (Simple & Fast)

`read_message`

Read current board content

// No parameters needed if env var is set
{}

`send_text_message` ⭐ Most Popular

Send simple text - easiest way to update your board!

{
  "text": "Hello AI World!"
}

`send_characters_rw`

Send character array using Read/Write API

{
  "characters": [[0,8,5,12,12,15,0,1,9,...], [...], ...] // 6x22 array
}

🔧 Subscription API Tools (Advanced)

`list_subscriptions`

Get all your Vestaboard subscriptions

{} // Uses env vars or pass api_key/api_secret

`send_message`

Send to specific subscription

{
  "subscription_id": "your-subscription-id",
  "characters": [[...], [...], ...] // 6x22 array
}

`send_vbml_message`

Compose and send VBML in one step

{
  "subscription_id": "your-subscription-id",
  "components": [
    {
      "template": "{{greeting}} World!",
      "style": {"justify": "center", "align": "center"}
    }
  ],
  "props": {"greeting": "Hello"}
}

🎨 Utility Tools (AI-Friendly)

`string_to_characters`

Convert text to Vestaboard character array

{
  "text": "Hello World",
  "justify": "center" // "left", "center", "right"
}

`clear_board`

Create blank or filled boards

{
  "fill_character": 63 // Red background, or 0 for blank
}

`validate_board`

Validate character array before sending

{
  "characters": [[...], [...], ...] // Checks dimensions and codes
}

🎯 Universal Tools

`compose_vbml`

Create advanced layouts with VBML

{
  "components": [
    {
      "template": "{69}ALERT{69} System Status",
      "style": {
        "justify": "center",
        "align": "top",
        "height": 2
      }
    },
    {
      "template": "{{status_message}}",
      "style": {
        "justify": "center", 
        "align": "bottom",
        "height": 4
      }
    }
  ],
  "props": {
    "status_message": "All Systems Operational"
  }
}

`get_character_codes`

Character code reference

{
  "filter": "colors" // "all", "colors", "letters", "numbers", "symbols"
}

🎨 Advanced Examples

AI Status Dashboard

// Multi-component layout with dynamic content
{
  "components": [
    {
      "template": "{69}AI STATUS{69}",
      "style": {"justify": "center", "height": 1}
    },
    {
      "template": "{{status}}",
      "style": {"justify": "center", "align": "center", "height": 4}
    },
    {
      "template": "Last Update: {{time}}",
      "style": {"justify": "center", "align": "bottom", "height": 1}
    }
  ],
  "props": {
    "status": "{66}ONLINE{66} Processing 1.2k req/min",
    "time": "14:30:22"
  }
}

Color-Coded Alerts

// Different colors for different alert levels
{
  "text": "{63}CRITICAL{63} Server down {65}WARNING{65} High load {66}INFO{66} All good"
}

Artistic Patterns

// Create visual patterns with character codes
{
  "characters": [
    [63,64,65,66,67,68,69,70,71,63,64,65,66,67,68,69,70,71,63,64,65,66],
    [64,65,66,67,68,69,70,71,63,64,65,66,67,68,69,70,71,63,64,65,66,67],
    [65,66,67,68,69,70,71,63,64,65,66,67,68,69,70,71,63,64,65,66,67,68],
    [66,67,68,69,70,71,63,64,65,66,67,68,69,70,71,63,64,65,66,67,68,69],
    [67,68,69,70,71,63,64,65,66,67,68,69,70,71,63,64,65,66,67,68,69,70],
    [68,69,70,71,63,64,65,66,67,68,69,70,71,63,64,65,66,67,68,69,70,71]
  ]
}

🎯 Character Code Reference

Colors (Perfect for Black Vestaboards)

63: 🔴 RED (alerts, urgent)
64: 🟠 ORANGE (warnings)
65: 🟡 YELLOW (attention, maximum visibility)
66: 🟢 GREEN (success, normal)
67: 🔵 BLUE (info, professional)
68: 🟣 VIOLET (special, elegant)
69: ⚪ WHITE (highest contrast, headers)
70: ⚫ BLACK (blocks, backgrounds)
71: ⬜ FILLED (inverted contrast)

Text Characters

1-26: A-Z (letters)
27-36: 1-0 (numbers)
37-62: Punctuation (!, @, #, $, etc.)
0: BLANK (space)

🔒 Security Best Practices

Environment Variables

# .env file
VESTABOARD_READ_WRITE_KEY=your-key-here
# OR for subscription API
VESTABOARD_API_KEY=your-api-key
VESTABOARD_API_SECRET=your-api-secret

Credential Management

✅ Never commit credentials to version control
✅ Use environment variables or secure vaults
✅ Rotate keys regularly
✅ Use Read/Write API for simpler auth when possible

⚡ Performance & Rate Limits

Vestaboard Limits

15 Second Rule: Messages sent within 15 seconds are ignored
Rate Limiting: APIs return 503 after ~15 seconds of rapid requests
Message Size: 6 rows × 22 columns (132 characters max)

Optimization Tips

// ✅ Good: Single message with all info
{
  "text": "{69}STATUS{69} {66}OK{66} Server: 99.9% {65}Queue: 234{65}"
}

// ❌ Avoid: Rapid successive messages (will be dropped)
// Don't send multiple messages quickly

🚀 Why This MCP Server is Superior

vs. Direct API Calls

✅ 12 Tools vs Manual Coding: Pre-built, tested functions
✅ Error Handling: Comprehensive validation and helpful messages
✅ Utility Functions: Text conversion, validation, board management
✅ Rate Limit Awareness: Built-in warnings and best practices

vs. Other MCP Servers

✅ Most Complete: 12 tools covering all Vestaboard features
✅ Dual API Support: Both simple and advanced usage patterns
✅ Production Ready: Real-world tested with proper error handling
✅ AI Optimized: Designed for AI systems with helpful descriptions

vs. Official SDK

✅ MCP Integration: Works with any MCP-compatible AI system
✅ No Code Required: AI agents can use directly without programming
✅ Enhanced Utilities: Additional functions not in official SDK
✅ Better Documentation: Comprehensive examples and guides

🧪 Testing

# Run built-in tests
npm test

# Test with environment variables
VESTABOARD_READ_WRITE_KEY="test" npm test

# Manual testing
node -e "console.log('Testing Vestaboard MCP Server')"

📊 API Endpoints Reference

Read/Write API (Simple)

Base: https://rw.vestaboard.com/
Auth: X-Vestaboard-Read-Write-Key header
Methods: GET (read), POST (send)

Subscription API (Advanced)

Subscriptions: https://subscriptions.vestaboard.com/subscriptions
Messages: https://subscriptions.vestaboard.com/subscriptions/{id}/message
Auth: X-Vestaboard-Api-Key + X-Vestaboard-Api-Secret headers

VBML Composition

Compose: https://vbml.vestaboard.com/compose
Format: https://vbml.vestaboard.com/format (legacy)

🤝 Contributing

We welcome contributions! This MCP server is designed to be the most complete Vestaboard integration available.

Development Setup

git clone https://github.com/vestaboard/vestaboard-mcp.git
cd vestaboard-mcp
npm install
npm test

Adding Features

New tools should follow the existing pattern
Include comprehensive JSDoc comments
Add error handling and validation
Update README with examples

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Vestaboard for the amazing hardware and APIs
Model Context Protocol for the integration standard
vestaboard-api npm package for inspiration
The MCP community for feedback and contributions

Ready to transform your Vestaboard into an AI-controlled display?

npm install -g vestaboard-mcp

The most complete, production-ready Vestaboard MCP server available. 🚀