ykhli/mcp-vestaboard

Vestaboard MCP Server

Give Cursor agent the ability to display messages on your Vestaboard.

More examples:

Features

• Text Mode: Send simple text messages that are automatically formatted and centered by Vestaboard
• Board Mode: Full control over the 6×22 character grid with precise positioning
• Color Support: Use Vestaboard's built-in color codes (Red, Orange, Yellow, Green, Blue, Violet, White, Black)
• Symbol Support: Display special characters, numbers, and punctuation
• MCP Integration: Works seamlessly with AI assistants that support the Model Context Protocol

Installation

1. Clone this repository:

git clone <repository-url>
cd vestaboard-mcp

2. Install dependencies:

npm install

Getting Your Vestaboard API Key

1. Visit Vestaboard Developer Portal
2. Sign in with your Vestaboard account
3. Go to "Read/Write API" section
4. Generate a new API key for your board
5. Copy the key to your .env file

Usage

Adding to Cursor as an MCP Server

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Go to "Features" → "Model Context Protocol"
3. Add a new MCP server by copying and pasting this JSON configuration:

{
  "mcpServers": {
    "vestaboard": {
      "command": "npx",
      "args": ["-y", "tsx", "path/to/vestaboard-mcp/index.ts"],
      "env": {
        "VESTABOARD_API_KEY": "YOUR_API_KEY"
      }
    }
}

Important:

• Replace /absolute/path/to/vestaboard-mcp with the actual absolute path to your cloned repository
• Replace your_vestaboard_api_key_here with your actual Vestaboard API key

4. Save the configuration and restart Cursor

Using with Cursor

Once configured, you can ask Cursor to display messages on your Vestaboard using natural language. Cursor will automatically use the display_message tool to send messages to your Vestaboard.

Examples:

• "Display 'Good Morning!' on my Vestaboard"
• "Show a colorful welcome message on the Vestaboard"
• "Put 'Meeting in 5 mins' on my Vestaboard in red"
• "Draw a minimal portrait of a Pikachu on my Vestaboard"

Text Mode (Default)

{
  "message": "Hello World!",
  "mode": "text"
}

Board Mode (Advanced)

{
  "mode": "board",
  "board": [
    [0, 0, 8, 5, 12, 12, 15, 0, 23, 15, 18, 12, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
  ]
}

Character and Color Codes

Letters

• A-Z: 1-26

Numbers

• 0-9: 36, 27-35

Special Characters

• Blank: 0
• !: 37
• @: 38
• #: 39
• $: 40
• (: 41
• ): 42
• -: 44
• +: 46
• &: 47
• =: 48
• ;: 49
• :: 50
• ': 52
• ": 53
• %: 54
• ,: 55
• .: 56
• /: 59
• ?: 60
• °: 62

Colors

• Red: 63
• Orange: 64
• Yellow: 65
• Green: 66
• Blue: 67
• Violet: 68
• White: 69
• Black: 70
• Filled: 71

Project Structure

vestaboard-mcp/
├── code.ts           # Vestaboard character and color code mappings
├── index.ts          # Main MCP server implementation
├── sendMessage.js    # Test utility for sending messages
├── package.json      # Node.js dependencies
└── README.md         # This file

API Reference

Tool: display_message

Displays a message on the Vestaboard using either text mode or board mode.

Parameters

• message (string, optional): The text message to display (required for text mode)
• mode (enum, optional): Display mode - "text" or "board" (default: "text")
• board (array, optional): 6×22 array of Vestaboard codes (required for board mode)

Response

Returns a success message indicating the content was displayed on the Vestaboard.

Examples

Simple Text Message

// When you say: "Display 'Good Morning!' on my Vestaboard"
// Cursor sends:
{
  "message": "Good Morning!",
  "mode": "text"
}

Colorful Message with Board Mode

// When you say: "Create a colorful hello world message on my Vestaboard"
// Cursor sends:
{
  "mode": "board",
  "board": [
    [63, 63, 8, 5, 12, 12, 15, 63, 63, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [66, 66, 23, 15, 18, 12, 4, 66, 66, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
  ]
}

Requirements

• Node.js 16 or higher
• A Vestaboard device
• Vestaboard API key
• Cursor IDE with MCP support

License

This project is open source and available under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues related to:

• Vestaboard API: Check the Vestaboard Developer Documentation
• MCP Protocol: See the Model Context Protocol Documentation
• This Project: Open an issue in this repository