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

Network Tools (15+ tools)

• network.status - Get network status
• network.connect - Connect to WiFi
• network.scan - Scan for networks
• network.startAP - Start access point
• network.httpRequest - Make HTTP requests
• network.ping - Ping hosts
• network.getTime - Get NTP time
• network.setMDNS - Configure mDNS

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

1. Install PlatformIO or Arduino IDE

2. Clone this repository

3. Open the project in PlatformIO

4. 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

1. Power on the ESP32 CYD board

2. Connect to WiFi or use the AP mode

3. Find the device IP address on the display

4. 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

1. Create header file in include/tools/

2. Implement in src/tools/

3. Register tools in the registerTools() method

4. 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