HelloWorld
登录
n

nodemcu-mcp服务

一项用于管理ESP8266/NodeMCU物联网设备的服务，该服务同时提供REST/WebSocket API，并实现了模型上下文协议以集成AI助手。

home-automation-and-iotos-automation

286 查看 · 2026-07-07 更新

简介

一项用于管理ESP8266/NodeMCU物联网设备的服务，该服务同时提供REST/WebSocket API，并实现了模型上下文协议以集成AI助手。

简介

一项用于管理ESP8266/NodeMCU物联网设备的服务，该服务同时提供REST/WebSocket API，并实现了模型上下文协议以集成AI助手。

NodeMCU MCP (Model Context Protocol) 服务

NodeMCU MCP Logo

GitHub license npm version smithery badge

这是一个用于管理NodeMCU设备的模型上下文协议（MCP）服务。该服务既提供了标准的RESTful API/WebSocket接口，也实现了模型上下文协议，以便与像Claude Desktop这样的AI工具集成。

概览

NodeMCU MCP为ESP8266/NodeMCU IoT设备提供了一个管理解决方案，具有以下关键功能：

  • 监控设备状态和遥测数据
  • 远程发送命令给设备
  • 更新设备配置
  • 通过MCP协议与AI助手集成

可视化

NodeMCU MCP架构
系统架构概览

NodeMCU MCP数据流
组件间的数据流动

Claude + NodeMCU MCP工作流程
Claude Desktop如何与NodeMCU设备交互

特性

  • 🔌 设备管理：注册、监控和控制NodeMCU设备
  • 📊 实时通讯：WebSocket接口支持实时更新
  • ⚙️ 配置管理：远程更新设备设置
  • 🔄 命令执行：远程发送重启、更新、状态等命令
  • 📡 遥测收集：收集传感器数据和设备指标
  • 🔐 认证：使用JWT认证安全访问API
  • 🧠 AI集成：与Claude Desktop及其他MCP兼容的AI工具协同工作

快速开始

前提条件

  • Node.js 16.x 或更高版本
  • npm 或 yarn
  • 对于NodeMCU客户端：支持ESP8266的Arduino IDE

安装

通过Smithery安装

要通过Smithery自动安装适用于Claude Desktop的NodeMCU Manager：

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

从npm安装（一旦发布）

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

# Local installation
npm install nodemcu-mcp

从源码安装

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

配置

  1. 根据示例创建一个.env文件：

    cp .env.example .env

  2. 使用您的设置更新.env文件：

    # 服务器配置
PORT=3000
HOST=localhost

# 安全
JWT_SECRET=your_strong_random_secret_key

# 日志级别 (error, warn, info, debug)
LOG_LEVEL=info

使用

作为API服务器运行

开发模式带自动重启：

npm run dev

生产模式：

npm start

作为MCP服务器运行

为了与Claude Desktop或其他MCP客户端集成：

npm run mcp

如果全局安装了：

nodemcu-mcp --mode=mcp

命令行选项

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集成

此项目现在使用官方的 Model Context Protocol (MCP) TypeScript SDK 来提供与 Claude for Desktop 及其他 MCP 客户端的集成。

MCP 工具

以下工具可以通过 MCP 接口获得：

  • list-devices: 列出所有注册的 NodeMCU 设备及其状态
  • get-device: 获取特定 NodeMCU 设备的详细信息
  • send-command: 向 NodeMCU 设备发送命令
  • update-config: 更新 NodeMCU 设备的配置

与 Claude for Desktop 一起使用

要将此服务器与 Claude for Desktop 一起使用，请执行以下步骤：

  1. 从 https://claude.ai/desktop 安装 Claude for Desktop
  2. 通过编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 配置 Claude for Desktop:
{
  "mcpServers": {
    "nodemcu": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/YOUR/PROJECT/mcp_server_sdk.js"
      ]
    }
  }
}
  1. 重启 Claude for Desktop
  2. 现在你应该能在 Claude for Desktop 界面中看到 NodeMCU 工具了

单独运行 MCP 服务器

要直接运行 MCP 服务器：

npm run mcp

或者使用 CLI：

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

API 文档

认证

  • POST /api/auth/login - 登录并获取 JWT 令牌

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

    响应:

    {
  "message": "登录成功",
  "token": "your.jwt.token",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin"
  }
}

  • POST /api/auth/validate - 验证 JWT 令牌

    {
  "token": "your.jwt.token"
}

设备 API

所有设备端点都需要使用 JWT 令牌进行身份验证：

Authorization: Bearer your.jwt.token

列出设备

GET /api/devices

响应:

{
  "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 /api/devices/:id

响应:

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

向设备发送命令

POST /api/devices/:id/command

请求:

{
  "command": "restart",
  "params": {}
}

响应:

{
  "message": "Command sent to device",
  "command": "restart",
  "params": {},
  "response": {
    "success": true,
    "message": "Device restarting"
  }
}

WebSocket 协议

WebSocket 服务器位于根路径：ws://your-server:3000/

有关 WebSocket 协议消息的详细信息，请参阅代码或示例目录。

NodeMCU 客户端设置

请参考 examples 目录中的 Arduino 草图，以获取完整的客户端实现。

关键步骤

  1. 在 Arduino IDE 中安装所需的库：

    • ESP8266WiFi
    • WebSocketsClient
    • ArduinoJson

  2. 使用你的 WiFi 和服务器设置配置草图：

    // WiFi 凭据
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

// MCP 服务器设置
const char* mcpHost = "your-server-ip";
const int mcpPort = 3000;

  3. 将草图上传到你的 NodeMCU 设备

开发

项目结构

nodemcu-mcp/
├── assets/             # Logo and other static assets
├── bin/                # CLI scripts
├── examples/           # Example client code
├── middleware/         # Express middleware
├── routes/             # API routes
├── services/           # Business logic
├── .env.example        # Environment variables example
├── index.js            # API server entry point
├── mcp_server.js       # MCP protocol implementation
├── mcp-manifest.json   # MCP manifest
└── package.json        # Project configuration

贡献

欢迎贡献！请随时提交 Pull Request。

  1. 分叉仓库
  2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
  3. 提交你的更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 打开一个 Pull Request

许可证

请注意，原始文本中的 #8, #9, #10, #11, #12, #13, #14, #15, #16, #17, #18, #19 应被实际内容替换。这些标记在这里保留是为了保持格式一致。

此项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

MIT 许可证是一种宽松的许可证，它允许您：

  • 商业使用该软件
  • 修改该软件
  • 分发该软件
  • 私人使用和修改该软件

唯一的要求是必须随软件一起包含许可证和版权声明。

致谢

工具列表

  • list-devices:

  • get-device:

  • send-command:

  • update-config:

服务配置

[{'mcpServers': {'nodemcu': {'args': ['/ABSOLUTE/PATH/TO/YOUR/PROJECT/mcp_server_sdk.js'], 'command': 'node'}}}]

来源