MCP 服务器

NodeMCU MCP Service

一个用于管理 ESP8266/NodeMCU 物联网设备的服务器，它提供 REST/WebSocket API，并实现了模型上下文协议，以便与 AI 助手集成。

Tools

list-devices

get-device

send-command

update-config

README

NodeMCU MCP (模型上下文协议) 服务

用于管理 NodeMCU 设备的模型上下文协议 (MCP) 服务。此服务提供标准的 RESTful API/WebSocket 接口，并实现了模型上下文协议，以便与 Claude Desktop 等 AI 工具集成。

概述

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

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

可视化

<img src="assets/architecture-diagram.svg" alt="NodeMCU MCP Architecture" width="600" /> 系统架构概述

<img src="assets/dataflow-diagram.svg" alt="NodeMCU MCP Data Flow" width="600" /> 组件之间的数据流

<img src="assets/mcp-workflow.svg" alt="Claude + NodeMCU MCP Workflow" width="600" /> 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：

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

从 npm 安装 (发布后)

# 全局安装（推荐用于 MCP 集成）
npm install -g nodemcu-mcp

# 本地安装
npm install nodemcu-mcp

从源代码安装

# 克隆存储库
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 服务器运行

具有自动重启的开发模式：

npm run dev

生产模式：

npm start

作为 MCP 服务器运行

用于与 Claude Desktop 或其他 MCP 客户端集成：

npm run mcp

如果全局安装：

nodemcu-mcp --mode=mcp

命令行选项

Usage: nodemcu-mcp [options]

Options:
  -m, --mode   运行模式 (mcp, api, both)  [string] [default: "both"]
  -p, --port   API 服务器端口        [number] [default: 3000]
  -h, --help   显示帮助                  [boolean]
  --version    显示版本号        [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 for Desktop
现在您应该在 Claude for Desktop 界面中看到 NodeMCU 工具

独立运行 MCP 服务器

要直接运行 MCP 服务器：

npm run mcp

或者使用 CLI：

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

API 文档

身份验证

POST /api/auth/login - 登录并获取 JWT 令牌

{
  "username": "admin",
  "password": "admin123"
}

响应:

{
  "message": "登录成功",
  "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": "restart",
  "params": {},
  "response": {
    "success": true,
    "message": "设备正在重启"
  }
}

WebSocket 协议

WebSocket 服务器在根路径可用：ws://your-server:3000/

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

NodeMCU 客户端设置

有关完整的客户端实现，请参阅 examples 目录中的 Arduino sketch。

主要步骤

在 Arduino IDE 中安装所需的库：
- ESP8266WiFi
- WebSocketsClient
- ArduinoJson

使用您的 WiFi 和服务器设置配置 sketch：

// WiFi 凭据
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

// MCP 服务器设置
const char* mcpHost = "your-server-ip";
const int mcpPort = 3000;

将 sketch 上传到您的 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。

Fork 存储库
创建您的功能分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。

MIT 许可证是一个允许性许可证，允许您：

将该软件用于商业用途
修改该软件
分发该软件
私下使用和修改该软件

致谢

模型上下文协议用于集成规范
NodeMCU 用于出色的 IoT 平台
Anthropic 用于 Claude Desktop