NodeMCU MCP（模型上下文协议）服务
用于管理 NodeMCU 设备的模型上下文协议 (MCP) 服务。该服务提供标准的 RESTful API/WebSocket 接口，并实现模型上下文协议，以便与 Claude Desktop 等 AI 工具集成。
概述
NodeMCU MCP 为 ESP8266/NodeMCU IoT 设备提供了管理解决方案，具有以下主要功能：
- 监控设备状态和遥测
- 远程向设备发送命令
- 更新设备配置
- 通过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：
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 .
配置
- 根据示例创建一个
.env文件： - 使用您的设置更新
.env文件：# Server Configuration
PORT=3000
HOST=localhost
# Security
JWT_SECRET=your_strong_random_secret_key
# Log Level (error, warn, info, debug)
LOG_LEVEL=info
用法
作为 API 服务器运行
具有自动重启的开发模式：
生产方式：
作为 MCP 服务器运行
与 Claude Desktop 或其他 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 集成
该项目现在使用官方模型上下文协议 (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：
{
"mcpServers": {
"nodemcu": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/TO/YOUR/PROJECT/mcp_server_sdk.js"
]
}
}
}
- 重启 Claude 桌面版
- 您现在应该在 Claude for Desktop 界面中看到 NodeMCU 工具
独立运行 MCP 服务器
要直接运行 MCP 服务器：
或者使用 CLI：
API 文档
验证
- POST /api/auth/login - 登录并获取 JWT 令牌
{
"username": "admin",
"password": "admin123"
}
{
"message": "Login successful",
"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
列出设备
回复：
{
"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"
}
]
}
获取设备详细信息
回复：
{
"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 草图以获得完整的客户端实现。
关键步骤
- 在 Arduino IDE 中安装所需的库：
- ESP8266WiFi
- WebSockets客户端
- ArduinoJson
- 使用您的 WiFi 和服务器设置配置草图：
// WiFi credentials
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
// MCP Server settings
const char* mcpHost = "your-server-ip";
const int mcpPort = 3000;
- 将草图上传到您的 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 请求。
- 分叉存储库
- 创建你的功能分支（
git checkout -b feature/amazing-feature ） - 提交您的更改（
git commit -m 'Add some amazing feature' ） - 推送到分支（
git push origin feature/amazing-feature ） - 打开拉取请求
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。
MIT 许可证是一种许可证，允许您：
- 将软件用于商业用途
- 修改软件
- 分发软件
- 私自使用和修改软件
唯一的要求是许可证和版权声明必须包含在软件中。
致谢