Glama
Sign In

NodeMCU MCP Service

by amanasmuei
Verified
GitHub
JavaScript
MIT License
1
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

  • Connects with ESP8266 devices through Arduino IDE, providing device management capabilities for NodeMCU devices including monitoring, configuration, and command execution.

  • Runs as a Node.js application, providing RESTful API and WebSocket interfaces for NodeMCU device management.

NodeMCU MCP (Model Context Protocol) Service

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

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

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

  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

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:

  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.

NodeMCU Client Setup

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

Key Steps

  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

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

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

A service for managing ESP8266/NodeMCU IoT devices that provides both REST/WebSocket APIs and implements the Model Context Protocol for AI assistant integration.

  1. Overview
    1. Visualizations
      1. Features
        1. Quick Start
          1. Prerequisites
          2. Installation
          3. Configuration
        2. Usage
          1. Running as API Server
          2. Running as MCP Server
          3. Command Line Options
        3. MCP Integration
          1. MCP Tools
          2. Using with Claude for Desktop
          3. Running the MCP Server Standalone
        4. API Documentation
          1. Authentication
          2. Devices API
        5. WebSocket Protocol
          1. NodeMCU Client Setup
            1. Key Steps
          2. Development
            1. Project Structure
            2. Contributing
          3. License
            1. Acknowledgments