# Vestaboard MCP Server

![64C141F8-7167-4460-AB9F-FA4E4BBDCE19](https://github.com/user-attachments/assets/b33df4ee-2c1d-4682-9741-19f73265aaf1)

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

More examples: 
<img width="1301" height="733" alt="Screenshot 2025-09-12 at 8 22 42 AM" src="https://github.com/user-attachments/assets/993a6153-e100-483a-95a1-1244c04ec7f9" />



## 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:

```bash
git clone <repository-url>
cd vestaboard-mcp
```

2. Install dependencies:

```bash
npm install
```

## Getting Your Vestaboard API Key

1. Visit [Vestaboard Developer Portal](https://web.vestaboard.com/)
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:

```json
{
  "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)

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

#### Board Mode (Advanced)

```json
{
  "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

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

### Colorful Message with Board Mode

```javascript
// 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](https://docs.vestaboard.com/)
- **MCP Protocol**: See the [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- **This Project**: Open an issue in this repository