Labsco
amanasmuei logo

NodeMCU MCP

★ 1

from amanasmuei

An MCP service for managing NodeMCU (ESP8266) IoT devices.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#git#security

MseeP.ai Security Assessment Badge

NodeMCU MCP (Model Context Protocol) Service

NodeMCU MCP Logo

smithery badge

A Model Context Protocol (MCP) service for managing NodeMCU devices. This service provides both a standard RESTful API/WebSocket interface and implements the Model Context Protocol for integration with AI tools like Claude Desktop.

Overview

NodeMCU MCP provides a management solution for ESP8266/NodeMCU IoT devices with these key capabilities:

  • Monitor device status and telemetry
  • Send commands to devices remotely
  • Update device configurations
  • Integration with AI assistants through MCP protocol

Visualizations

NodeMCU MCP Architecture
System Architecture Overview

NodeMCU MCP Data Flow
Data Flow Between Components

Claude + NodeMCU MCP Workflow
How Claude Desktop Interacts with NodeMCU Devices

Features

  • 🔌 Device Management: Register, monitor, and control NodeMCU devices
  • 📊 Real-time Communication: WebSocket interface for real-time updates
  • ⚙️ Configuration Management: Update device settings remotely
  • 🔄 Command Execution: Send restart, update, status commands remotely
  • 📡 Telemetry Collection: Gather sensor data and device metrics
  • 🔐 Authentication: Secure API access with JWT authentication
  • 🧠 AI Integration: Work with Claude Desktop and other MCP-compatible AI tools

MCP Integration

This project now uses the official Model Context Protocol (MCP) TypeScript SDK to provide integration with Claude for Desktop and other MCP clients.

MCP Tools

The following tools are available through the MCP interface:

  • list-devices: List all registered NodeMCU devices and their status
  • get-device: Get detailed information about a specific NodeMCU device
  • send-command: Send a command to a NodeMCU device
  • update-config: Update the configuration of a NodeMCU device

Using with Claude for Desktop

To use this server with Claude for Desktop:

  1. Install Claude for Desktop from https://claude.ai/desktop
  2. Configure Claude for Desktop by editing ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "nodemcu": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/YOUR/PROJECT/mcp_server_sdk.js"
      ]
    }
  }
}
  1. Restart Claude for Desktop
  2. You should now see the NodeMCU tools in the Claude for Desktop interface

Running the MCP Server Standalone

To run the MCP server directly:

npm run mcp

Or using the CLI:

./bin/cli.js --mode=mcp

API Documentation

Authentication

  • POST /api/auth/login - Login and get JWT token

    {
  "username": "admin",
  "password": "admin123"
}

    Response:

    {
  "message": "Login successful",
  "token": "your.jwt.token",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin"
  }
}

  • POST /api/auth/validate - Validate JWT token

    {
  "token": "your.jwt.token"
}

Devices API

All device endpoints require authentication with a JWT token:

Authorization: Bearer your.jwt.token

List Devices

GET /api/devices

Response:

{
  "count": 1,
  "devices": [
    {
      "id": "nodemcu-001",
      "name": "Living Room Sensor",
      "type": "ESP8266",
      "status": "online",
      "ip": "192.168.1.100",
      "firmware": "1.0.0",
      "lastSeen": "2023-05-15T14:30:45.123Z"
    }
  ]
}

Get Device Details

GET /api/devices/:id

Response:

{
  "id": "nodemcu-001",
  "name": "Living Room Sensor",
  "type": "ESP8266",
  "status": "online",
  "ip": "192.168.1.100",
  "firmware": "1.0.0",
  "lastSeen": "2023-05-15T14:30:45.123Z",
  "config": {
    "reportInterval": 30,
    "debugMode": false,
    "ledEnabled": true
  },
  "lastTelemetry": {
    "temperature": 23.5,
    "humidity": 48.2,
    "uptime": 3600,
    "heap": 35280,
    "rssi": -68
  }
}

Send Command to Device

POST /api/devices/:id/command

Request:

{
  "command": "restart",
  "params": {}
}

Response:

{
  "message": "Command sent to device",
  "command": "restart",
  "params": {},
  "response": {
    "success": true,
    "message": "Device restarting"
  }
}

WebSocket Protocol

The WebSocket server is available at the root path: ws://your-server:3000/

For details on the WebSocket protocol messages, refer to the code or the examples directory.

Development

Project Structure

nodemcu-mcp/
├── assets/             # Logo and other static assets
├── bin/                # CLI scripts
├── examples/           # Example client code
├── middleware/         # Express middleware
├── routes/             # API routes
├── services/           # Business logic
├── .env.example        # Environment variables example
├── index.js            # API server entry point
├── mcp_server.js       # MCP protocol implementation
├── mcp-manifest.json   # MCP manifest
└── package.json        # Project configuration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request