NodeMCU MCP server for AI agents

NodeMCU MCP Service is a management solution for ESP8266/NodeMCU IoT devices that implements the Model Context Protocol (MCP). It allows you to monitor device status, send commands remotely, update configurations, and integrate with AI assistants like Claude Desktop through the MCP protocol.

Prerequisites

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

Installation Options

Via Smithery

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

From npm

# 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

Running the Server

As API Server

Development mode with auto-restart:

npm run dev

Production mode:

npm start

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 with Claude Desktop

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

Available MCP Tools

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

API Usage

Authentication

Login and get JWT token

POST /api/auth/login

Request body:

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

Response:

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

Validate JWT token

POST /api/auth/validate

Request body:

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

NodeMCU Client Setup

Arduino IDE Setup

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "nodemcu" '{"command":"node","args":["path/to/mcp_server_sdk.js"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "nodemcu": {
            "command": "node",
            "args": [
                "path/to/mcp_server_sdk.js"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "nodemcu": {
            "command": "node",
            "args": [
                "path/to/mcp_server_sdk.js"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect