esp-cyd-mcp

Control esp cyd with mcp

3 stars C++Others Updated Aug 14, 2025

Documentation

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

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

bash

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

json

{
  "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:

json

{
  "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:

json

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

code

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