NodeMCU MCP Service - MCP Server

NodeMCU MCP (Model Context Protocol) Service

GitHub license

npm version

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

<img src="assets/architecture-diagram.svg" alt="NodeMCU MCP Architecture" width="600" /> System Architecture Overview <img src="assets/dataflow-diagram.svg" alt="NodeMCU MCP Data Flow" width="600" /> Data Flow Between Components <img src="assets/mcp-workflow.svg" alt="Claude + NodeMCU MCP Workflow" width="600" /> 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

Quick Start

Prerequisites

Node.js 16.x or higher
npm or yarn
For the NodeMCU client: Arduino IDE with ESP8266 support

Installation

Installing via Smithery

To install NodeMCU Manager for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @amanasmuei/nodemcu-mcp --client claude

From npm (once published)

# Global installation (recommended for MCP integration)
npm install -g nodemcu-mcp

# Local installation
npm install nodemcu-mcp

From source

# Clone the repository
git clone https://github.com/amanasmuei/nodemcu-mcp.git
cd nodemcu-mcp

# Install dependencies
npm install

# Optional: Install globally for MCP integration
npm install -g .

Configuration

Create a .env file based on the example:
```
cp .env.example .env
```

Update the .env file with your settings:

# Server Configuration
PORT=3000
HOST=localhost

# Security
JWT_SECRET=your_strong_random_secret_key

# Log Level (error, warn, info, debug)
LOG_LEVEL=info

Usage

Running as API Server

Development mode with auto-restart:

npm run dev

Production mode:

npm start

Running as MCP Server

For integration with Claude Desktop or other MCP clients:

npm run mcp

If installed globally:

nodemcu-mcp --mode=mcp

Command Line Options

Usage: nodemcu-mcp [options]

Options:
  -m, --mode   Run mode (mcp, api, both)  [string] [default: "both"]
  -p, --port   Port for API server        [number] [default: 3000]
  -h, --help   Show help                  [boolean]
  --version    Show version number        [boolean]

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:

Install Claude for Desktop from https://claude.ai/desktop
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"
      ]
    }
  }
}

Restart Claude for Desktop
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.

NodeMCU Client Setup

Refer to the Arduino sketch in the examples directory for a complete client implementation.

Key Steps

Install required libraries in Arduino IDE:
- ESP8266WiFi
- WebSocketsClient
- ArduinoJson

Configure the sketch with your WiFi and server settings:

// WiFi credentials
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

// MCP Server settings
const char* mcpHost = "your-server-ip";
const int mcpPort = 3000;

Upload the sketch to your NodeMCU device

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.

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License is a permissive license that allows you to:

Use the software commercially
Modify the software
Distribute the software
Use and modify the software privately

The only requirement is that the license and copyright notice must be included with the software.

Acknowledgments

Model Context Protocol for the integration specification
NodeMCU for the amazing IoT platform
Anthropic for Claude Desktop