amanasmuei

@amanasmuei/mcp-server-nodemcu

0 Stars 288 次浏览 amanasmuei 更新于 2026-08-23

开发者工具

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

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 .

配置

根据示例创建.env文件：

cp .env.example .env
使用您的设置更新.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一起使用，请执行以下步骤：

从https://claude.ai/desktop安装Claude for Desktop
通过编辑~/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"
]
}
}
}

重启Claude for Desktop
您现在应该能在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草图以获得完整的客户端实现。

关键步骤

在Arduino IDE中安装所需的库：
- ESP8266WiFi
- WebSocketsClient
- ArduinoJson
使用您的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;
将草图上传到您的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。

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

许可证

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

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

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

致谢

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

查看源码项目主页