ESP32 CYD MCP Server

A comprehensive Model Context Protocol (MCP) server implementation for the ESP32 CYD (Cheap Yellow Display) board. This project provides extensive remote control capabilities for the ESP32-2432S028R board through a WebSocket-based MCP interface.

Features

MCP Server Core

WebSocket-based MCP protocol implementation
JSON-RPC 2.0 compliant
Real-time bidirectional communication
Multiple client support
Event notifications

Tool Categories

Display Tools (20+ tools)

display.clear - Clear screen with color
display.text - Draw text with positioning and styling
display.line - Draw lines with thickness
display.rectangle - Draw rectangle outlines
display.fillRectangle - Draw filled rectangles
display.circle - Draw circle outlines
display.fillCircle - Draw filled circles
display.pixel - Draw individual pixels
display.backlight - Control backlight on/off
display.brightness - Set display brightness (0-255)
display.rotation - Set display rotation (0-3)
display.progressBar - Draw progress bars
display.info - Get display information

Touch Tools (10+ tools)

touch.getState - Get current touch state
touch.enable - Enable/disable touch input
touch.calibrate - Calibrate touch screen
touch.getHistory - Get recent touch events
touch.simulate - Simulate touch events
touch.getCalibration - Get calibration values
touch.saveCalibration - Save calibration to file
Gesture detection (swipe support)

GPIO Tools (15+ tools)

gpio.pinMode - Set pin mode (input/output/PWM)
gpio.digitalWrite - Write digital value
gpio.digitalRead - Read digital value
gpio.analogWrite - PWM output
gpio.analogRead - Read analog value
gpio.attachInterrupt - Attach interrupts
gpio.setPWM - Configure PWM with frequency
gpio.tone - Generate tones
gpio.pulseIn - Measure pulse duration

Sensor Tools (10+ tools)

sensor.readTemperature - Read temperature sensor
sensor.readLight - Read light sensor
sensor.readInternalTemp - ESP32 internal temperature
sensor.readHallSensor - Built-in hall sensor
sensor.readBatteryVoltage - Power supply voltage
sensor.readAll - Read all sensors at once
sensor.calibrate - Calibrate sensors
sensor.getEnvironment - Environmental summary

System Tools (20+ tools)

system.info - Comprehensive system information
system.restart - Restart ESP32
system.sleep - Deep/light sleep modes
system.memory - Memory statistics
system.tasks - FreeRTOS task info
system.setCPUFrequency - CPU speed control
system.performanceMode - Performance optimization
system.factoryReset - Factory reset

File Tools (15+ tools)

file.list - List files/directories
file.read - Read file contents
file.write - Write to file
file.delete - Delete files
file.mkdir - Create directories
file.copy - Copy files
file.storage - Storage statistics
Support for SPIFFS and SD card

Audio Tools (15+ tools)

audio.tone - Play single tone
audio.playMelody - Play melodies
audio.beep - Simple beep sounds
audio.playPattern - Custom tone patterns
audio.notification - Notification sounds
audio.alarm - Alarm patterns
audio.setVolume - Volume control
Predefined melodies (Mario, Star Wars, etc.)

Hardware Requirements

ESP32-2432S028R (CYD) board
2.8" ILI9341 TFT display (240x320)
XPT2046 resistive touch controller
Optional: SD card for file storage
Optional: External sensors (temperature, light)

Installation

Install PlatformIO or Arduino IDE
Clone this repository
Open the project in PlatformIO
Build and upload to your ESP32 CYD board

git clone https://github.com/yourusername/esp32-cyd-mcp
cd esp32-cyd-mcp
pio run -t upload

Configuration

Edit include/config.h to customize:

WiFi credentials
Pin assignments
Server ports
Display settings
Sensor calibration

Usage

Connecting to the MCP Server

Power on the ESP32 CYD board
Connect to WiFi or use the AP mode
Find the device IP address on the display
Connect via WebSocket to ws://[IP]:3001

Example MCP Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/invoke",
  "params": {
    "name": "display.text",
    "arguments": {
      "text": "Hello MCP!",
      "x": 50,
      "y": 100,
      "color": "white",
      "size": 2
    }
  }
}

Using with Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "esp32-cyd": {
      "command": "websocat",
      "args": ["ws://192.168.1.100:3001"]
    }
  }
}

API Documentation

Tool Invocation

All tools are invoked using the standard MCP tools/invoke method:

{
  "method": "tools/invoke",
  "params": {
    "name": "tool.name",
    "arguments": { ... }
  }
}

Event Notifications

The server sends notifications for various events:

touch.event - Touch input events
sensor.update - Periodic sensor updates
network.event - Network state changes
gpio.interrupt - GPIO interrupt events

Development

Adding New Tools

Create header file in include/tools/
Implement in src/tools/
Register tools in the registerTools() method
Add initialization in main.cpp

Project Structure

esp32-cyd-mcp/
├── include/
│   ├── config.h           # Configuration
│   ├── mcp_server.h       # MCP server core
│   └── tools/            # Tool headers
├── src/
│   ├── main.cpp          # Main application
│   ├── mcp_server.cpp    # MCP implementation
│   └── tools/           # Tool implementations
├── platformio.ini        # PlatformIO config
└── README.md

Troubleshooting

WiFi Connection Issues: Check credentials in config.h
Touch Not Working: Run touch calibration tool
Display Issues: Verify display rotation setting
Memory Issues: Monitor free heap, reduce tool usage

License

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

Contributing

Contributions are welcome! Please submit pull requests or open issues for bugs and feature requests.

Acknowledgments

ESP32 community for hardware support
TFT_eSPI library for display drivers
MCP specification for protocol design

ESP32 CYD