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.

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

System Architecture Overview

Data Flow Between Components

How Claude Desktop Interacts with NodeMCU Devices

• 🔌 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

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

To install NodeMCU Manager for Claude Desktop automatically via Smithery:

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

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

# Local installation
npm install nodemcu-mcp

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

1. Create a .env file based on the example:

   cp .env.example .env
   

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

Development mode with auto-restart:

npm run dev

Production mode:

npm start

For integration with Claude Desktop or other MCP clients:

npm run mcp

If installed globally:

nodemcu-mcp --mode=mcp

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]

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

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

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"
      ]
    }
  }
}

3. Restart Claude for Desktop
4. You should now see the NodeMCU tools in the Claude for Desktop interface

To run the MCP server directly:

npm run mcp

Or using the CLI:

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

• 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"
  }

All device endpoints require authentication with a JWT token:

Authorization: Bearer your.jwt.token

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 /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
  }
}

POST /api/devices/:id/command

Request:

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

Response:

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

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.

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

1. Install required libraries in Arduino IDE:

   • ESP8266WiFi
   • WebSocketsClient
   • ArduinoJson

2. 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;

3. Upload the sketch to your NodeMCU device

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

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

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.

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