NodeMCU MCP provides a centralized management surface for ESP8266/NodeMCU devices with a RESTful API, WebSocket real-time updates, and AI-friendly MCP integration. You can run the MCP server standalone to manage devices, or connect Claude Desktop and other MCP clients to interact through the MCP tools. The server exposes endpoints to authenticate, list devices, retrieve device details, and send commands, as well as a WebSocket channel for live telemetry and control events. The MCP integration enables AI assistants to discover and operate devices via standardized tools such as list-devices, get-device, send-command, and update-config, making it easier to automate workflows and remote management.

To use the MCP interface, start the server with the provided CLI in MCP mode (mode=mcp). This will enable the MCP protocol surface and allow Claude Desktop or other MCP clients to query devices, issue commands, and receive real-time updates. The included MCP Tools section exposes a set of operations that Claude can leverage: list-devices to enumerate all registered NodeMCU devices; get-device to fetch a device’s full details; send-command to issue actions like restart or update; and update-config to remotely modify a device’s settings. The server also supports JWT-based authentication to secure access.

When connected through Claude Desktop, you can register the nodemcu MCP server in Claude’s MCP configuration so Claude can present a tailored UI for your devices. The WebSocket path is available at ws://your-server:3000/, allowing real-time telemetry and command feedback as devices report status or respond to actions.

Prerequisites:

• Node.js 16.x or higher
• npm or yarn
• Optional: Arduino IDE with ESP8266 support for NodeMCU client development

Installation steps:

1. Clone the repository (or use your preferred source): git clone https://github.com/amanasmuei/nodemcu-mcp cd nodemcu-mcp

2. Install dependencies: npm install

3. Optional: Install globally for MCP integration (recommended for easier access): npm install -g .

4. Create and configure environment variables (see .env.example in the project): cp .env.example .env

   Edit .env with your settings (PORT, HOST, JWT_SECRET, LOG_LEVEL, etc.)

5. Run the MCP server in MCP mode: npm run mcp

   Or via the CLI in MCP mode

   node bin/cli.js --mode=mcp

6. Verify the server is running by hitting the API or connecting via WebSocket at the configured port.

Tips and common considerations:

• Ensure PORT and HOST in your .env do not conflict with other services on your host.
• JWT_SECRET should be strong and kept secure; used for authenticating API requests.
• For Claude Desktop integration, ensure Claude can resolve the MCP server by configuring the mcpServers section in Claude’s config (e.g., nodemcu server with command node and the absolute path to the CLI/script if needed).
• The MCP Tools (list-devices, get-device, send-command, update-config) enable common device management tasks; use update-config to adjust reporting intervals or feature toggles on devices.
• If you’re using the standalone MCP server, the CLI and bin/cli.js provide flexible mode selection (mcp, api, or both). Ensure you start in the desired mode for your workflow.
• WebSocket support enables real-time telemetry and event streaming; ensure firewall rules allow ws/wss as appropriate.