Vestaboard MCP Server

A Model Context Protocol server for controlling Vestaboard displays via both cloud and local APIs.

Features

Cloud API Support: Send messages, read current display, manage transitions
Local API Support: Direct control of devices on your network
Message Formatting: Convert text to character codes automatically
Animation Effects: Animate message display with multiple strategies
Environment Configuration: Use .env files for API credentials (minimal deps)
Type Safe: Full Python type hints with mypy support

Installation

Prerequisites

Python 3.10+
A Vestaboard device

Setup

# Clone and install
git clone https://github.com/lintility/vestaboard-mcp.git
cd vestaboard-mcp
pip install -e .

# Configure credentials
cp src/.env.example .env

Edit .env with your API credentials:

VESTABOARD_CLOUD_TOKEN: Get from https://www.vestaboard.com/account/integrations
VESTABOARD_LOCAL_ENABLEMENT_TOKEN: Sent via email by Vestaboard
VESTABOARD_LOCAL_API_KEY: Auto-populated after enabling local API (optional)

Usage

Run the Server

python -m src.server

Configure with Claude

Add to ~/.config/claude/mcp.json:

{
  "mcpServers": {
    "vestaboard": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/vestaboard-mcp",
      "env": {
        "VESTABOARD_CLOUD_TOKEN": "your_token",
        "VESTABOARD_LOCAL_API_KEY": "your_local_key"
      }
    }
  }
}

Available Tools

Cloud API

cloud_read_message: Get current display
cloud_send_message: Send text or character codes
cloud_format_message: Convert text to character codes
cloud_get_transition: Get transition settings
cloud_set_transition: Set animation effects (wave, drift, curtain, classic)

Local API

local_enable_api: Activate local API (one-time setup)
local_send_message: Send message with optional animation
local_read_message: Read current display

Project Structure

vestaboard-mcp/
├── src/
│   ├── server.py           # MCP server implementation
│   ├── vestaboard.py       # API client classes
│   └── .env.example        # Configuration template
├── tests/
│   └── test_server.py      # Test suite
├── pyproject.toml          # Dependencies and config
└── README.md               # This file

Development

# Run tests
pytest tests/

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

Dependencies

Core:

mcp>=0.1.0 - Model Context Protocol SDK
httpx>=0.24.0 - Async HTTP client
python-dotenv>=1.0.0 - Environment configuration

Dev:

pytest>=7.4.0 - Testing
pytest-asyncio>=0.21.0 - Async test support
black>=23.0.0 - Code formatting
ruff>=0.0.275 - Linting
mypy>=1.0.0 - Type checking

vestaboard-mcp