NodeMCU MCP（模型上下文协议）服务

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

概述

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

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

可视化

功能

• 🔌 设备管理：注册、监控和控制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：

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

从npm安装（一旦发布）

bash

全局安装（推荐用于MCP集成）

npm install -g nodemcu-mcp

本地安装

npm install nodemcu-mcp

从源代码安装

bash

克隆仓库

git clone https://github.com/amanasmuei/nodemcu-mcp.git
cd nodemcu-mcp

安装依赖

npm install

可选：全局安装以进行MCP集成

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服务器运行

开发模式（带自动重启）：
bash
npm run dev

生产模式：
bash
npm start

作为MCP服务器运行

与Claude Desktop或其他MCP客户端集成时：
bash
npm run mcp

如果已全局安装：
bash
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:

json
{
"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服务器的方法如下：

bash
npm run mcp

或者使用CLI：

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

API文档

认证

• POST /api/auth/login - 登录并获取JWT令牌
  json
  {
  "username": "admin",
  "password": "admin123"
  }

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

• POST /api/auth/validate - 验证JWT令牌
  json
  {
  "token": "your.jwt.token"
  }

设备API

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

Authorization: Bearer your.jwt.token

列出设备

GET /api/devices

响应:
json
{
"count": 1,
"devices": [
{
"id": "nodemcu-001",
"name": "客厅传感器",
"type": "ESP8266",
"status": "在线",
"ip": "192.168.1.100",
"firmware": "1.0.0",
"lastSeen": "2023-05-15T14:30:45.123Z"
}
]
}

获取设备详情

GET /api/devices/:id

响应:
json
{
"id": "nodemcu-001",
"name": "客厅传感器",
"type": "ESP8266",
"status": "在线",
"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

请求:
json
{
"command": "restart",
"params": {}
}

响应:
json
{
"message": "命令已发送至设备",
"command": "restart",
"params": {},
"response": {
"success": true,
"message": "设备正在重启"
}
}

WebSocket协议

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

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

NodeMCU客户端设置

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

关键步骤

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

   • ESP8266WiFi
   • WebSocketsClient
   • ArduinoJson

2. 使用你的WiFi和服务器设置配置草图：
   cpp
   // 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和其他静态资源
├── bin/ # CLI脚本
├── examples/ # 示例客户端代码
├── middleware/ # Express中间件
├── routes/ # API路由
├── services/ # 业务逻辑
├── .env.example # 环境变量示例
├── index.js # API服务器入口点
├── mcp_server.js # MCP协议实现
├── mcp-manifest.json # MCP清单
└── package.json # 项目配置### 贡献

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

1. Fork 仓库
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

许可证

本项目采用 MIT 许可证进行许可 - 详情请参阅 LICENSE 文件。

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

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

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

致谢

• Model Context Protocol 提供了集成规范
• NodeMCU 提供了出色的物联网平台
• Anthropic 提供了 Claude Desktop