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

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

概述

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

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

可视化

系统架构概览

组件间的数据流

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：

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

3. 重启Claude for Desktop
4. 您现在应该能在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. 叉分仓库
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

服务配置

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

来源

• 来源：github
• 链接：https://github.com/amanasmuei/mcp-server-nodemcu