home / mcp / nodemcu mcp server
Manages ESP8266/NodeMCU devices via MCP with REST/WebSocket interfaces and AI tool integration.
Configuration
View docs{
"mcpServers": {
"amanasmuei-nodemcu-mcp": {
"command": "npm",
"args": [
"run",
"mcp"
]
}
}
}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.
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.
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-mcpCreate 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
```
```ini
# Example .env content
PORT=3000
HOST=localhost
JWT_SECRET=your_strong_random_secret_key
LOG_LEVEL=infoYou 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=mcpThe 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]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.
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.
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.
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.
List all registered NodeMCU devices and their status.
Fetch detailed information for a specific device by its identifier.
Send a command to a device (for example, restart or update).
Update the configuration settings of a device remotely.