NodeMCU

You manage and integrate NodeMCU ESP8266 devices with a dedicated MCP server that provides a RESTful API, WebSocket updates, device management, and seamless AI tool integration. This server lets you monitor telemetry, send remote commands, update configurations, and securely authenticate clients while working with MCP-compatible assistants like Claude Desktop.

How to use

Connect your MCP client (such as Claude Desktop or another MCP-enabled tool) to the NodeMCU MCP server to manage your ESP8266 devices. You can list devices, view details, send commands, and update device configurations from the client. The MCP integration enables real-time updates and structured command handling so your devices stay synchronized with your control plane.

Typical usage patterns include: registering devices, querying device status and telemetry, sending restart or update commands, and adjusting reporting intervals or debug settings. The secure API requires a JWT token; you log in, obtain a token, and present it with your requests. Use the MCP client to invoke the tools exposed by the server, such as listing devices, retrieving a specific device, issuing commands, or updating configurations.

How to install

Prerequisites you need before installing: Node.js 16.x or higher, npm or yarn, and Arduino IDE with ESP8266 support for the NodeMCU client side.

Step 1: Install via npm or npx to enable MCP integration with Claude Desktop.

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

# Local installation
npm install nodemcu-mcp

Configuration and startup

Create and populate environment configuration to run the server. Start with creating a .env file and adjusting the server port, host, and security settings.

cp .env.example .env

# Example .env content
PORT=3000
HOST=localhost
JWT_SECRET=your_strong_random_secret_key
LOG_LEVEL=info

Running the MCP server standalone

You can run the MCP server in MCP mode using the provided CLI or npm script. Choose the approach you prefer for your deployment.

npm run mcp

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

Command line options

The server supports a small set of CLI options to control how it runs and on which port. You can override defaults and select the run mode.

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]

Security and authentication

The API uses JWT-based authentication to securely access device data and management endpoints. You obtain a token by logging in with valid credentials, then include the token in the Authorization header for subsequent requests.

Configuration details and MCP integration

The server exposes an MCP interface that enables tools to perform device-related actions, including listing devices, querying device details, sending commands, and updating configurations. You’ll be able to work with Claude Desktop or other MCP clients using the MCP protocol.

Tools and endpoints overview

Available MCP tools include list-devices, get-device, send-command, and update-config. Use these tools through your MCP client to manage and control registered NodeMCU devices.

Additional notes

The server supports real-time telemetry via WebSocket and remote command execution to keep your devices synchronized with your control plane. Ensure your environment variables, especially JWT_SECRET and PORT, are securely configured to avoid unauthorized access.

Available tools

list-devices

List all registered NodeMCU devices and their status.

get-device

Fetch detailed information for a specific device by its identifier.

send-command

Send a command to a device (for example, restart or update).

update-config

Update the configuration settings of a device remotely.