NodeMCU MCP

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

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

概述

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

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

可视化

System Architecture Overview

Data Flow Between Components

How Claude Desktop Interacts with NodeMCU Devices

特性

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

快速开始

先决条件

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

安装

通过Smithery安装

通过以下方式自动安装克劳德桌面的NodeMCU管理器 铁匠铺:

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

1. 更新 .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服务器运行

自动重启开发模式：

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

该项目现在使用官方的模型上下文协议（MCP）TypeScript SDK为桌面和其他MCP客户端提供与Claude的集成。

MCP工具

以下工具可通过MCP接口使用：

• 列出设备：列出所有已注册的NodeMCU设备及其状态
• 获取设备：获取特定NodeMCU设备的详细信息
• 发送命令：向NodeMCU设备发送命令
• 更新配置：更新NodeMCU设备的配置

使用Claude for Desktop

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

1. 从以下位置安装Claude for Desktop https://claude.ai/desktop
2. 通过编辑为桌面配置Claude ~/Library/Application Support/Claude/claude_desktop_config.json:

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

1. 重新启动桌面版的Claude
2. 现在，您应该可以在Claude for Desktop界面中看到NodeMCU工具

独立运行MCP服务器

要直接运行MCP服务器：

npm run mcp

或者使用CLI：

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

API 文档

认证

• 发布/API/验证/登录 -登录并获取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

列出设备

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客户端设置

请参阅Arduino草图 examples 完整客户端实现的目录。

关键步骤

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

- ESP8266WiFi - WebSocketsClient - ArduinoJson

1. 使用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;

1. 将草图上传到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

贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

MIT许可证是一种许可证，允许您：

• 在商业上使用该软件
• 修改软件
• 分发软件
• 私下使用和修改软件

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

致谢

• 模型上下文协议 对于集成规范
• 令人惊叹的物联网平台
• Anthropic 克劳德桌面