home / mcp / nodemcu mcp server

NodeMCU MCP Server

Provides a configurable MCP server to manage NodeMCU devices, expose an API, and enable AI tool integration.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "amanasmuei-mcp-server-nodemcu": {
      "command": "npm",
      "args": [
        "run",
        "mcp"
      ]
    }
  }
}

You can manage and interact with NodeMCU devices through an MCP server that exposes a REST/WebSocket API and implements the Model Context Protocol. This server lets you monitor telemetry, send commands, adjust configurations, and integrate with MCP-enabled AI tools for streamlined device management.

How to use

You will connect an MCP client to this server to perform day-to-day management tasks. With the MCP interface, you can list registered NodeMCU devices, view device details, push commands like restart or update, and modify configurations. Real-time updates are available via WebSocket, enabling responsive dashboards and automation workflows.

Register devices and view their status
Query device details and telemetry
Send remote commands (restart, update, etc.)
Update device configurations remotely
Use MCP-compatible AI tools for automation and chat-based control

How to install

Prerequisites you need before installing include Node.js and a package manager.

# Prerequisites
node -v
npm -v

# Install via Smithery (if you want Claude Desktop integration)
npx -y @smithery/cli install @amanasmuei/nodemcu-mcp --client claude

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

# Local installation
npm install nodemcu-mcp

If you prefer to run the MCP server directly from source, you can build and start using the included CLI.

# From source (example workflow)
git clone https://github.com/amanasmuei/nodemcu-mcp.git
cd nodemcu-mcp
npm install
# Optional: install globally for MCP integration
npm install -g .

Configuration

Prepare environment variables to configure the server. Create a .env file and populate essential settings such as the API server port, host, and authentication secret.

cp .env.example .env
```

```bash
# Example values (adjust to your environment)
PORT=3000
HOST=localhost
JWT_SECRET=your_strong_random_secret_key
LOG_LEVEL=info

MCP server commands and integration points

You can run the MCP server in different modes depending on your setup. The following stand-alone commands start the MCP server in MCP mode for Claude Desktop or other MCP clients.

# Run via npm script (recommended for MCP integration)
npm run mcp

# Run via CLI directly (standalone MCP mode)
./bin/cli.js --mode=mcp

# If installed globally, you can invoke the binary directly
nodemcu-mcp --mode=mcp

API and MCP integration notes

Authentication is implemented via JWT tokens. Use the login endpoint to obtain a token and attach it to subsequent requests. The MCP interface exposes tools to list devices, fetch device details, send commands, and update configurations.

Available 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.