Skip to main content
Glama
enesjakozh
amanasmuei

NodeMCU MCP Service

by amanasmuei
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

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

GitHub 许可证 npm 版本 铁匠徽章

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

概述

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

  • 监控设备状态和遥测

  • 远程向设备发送命令

  • 更新设备配置

  • 通过MCP协议与AI助手集成

Related MCP server: MCP Personal Assistant Agent

可视化

特征

  • 🔌设备管理：注册、监控和控制 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 .

配置

  1. 根据示例创建一个.env文件：

    cp .env.example .env

  2. 使用您的设置更新.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 来提供与 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：

{
  "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 文档

验证

  • 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

列出设备

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

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

关键步骤

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

    • ESP8266WiFi

    • WebSockets客户端

    • ArduinoJson

  2. 使用您的 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;

  3. 将草图上传到您的 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 请求。

  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 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

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

  • 将软件用于商业用途

  • 修改软件

  • 分发软件

  • 私自使用和修改软件

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

致谢

Available Tools

4 tools
get-deviceD
ParametersJSON Schema
NameRequiredDescriptionDefault
deviceIdYesThe ID of the device to get information about

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-devicesD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send-commandD
ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe command to send (restart, update, status, etc.)
deviceIdYesThe ID of the device to send the command to
paramsNoOptional parameters for the command

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update-configD
ParametersJSON Schema
NameRequiredDescriptionDefault
configYesConfiguration parameters to update
deviceIdYesThe ID of the device to update configuration for

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedget-device
    • First observedlist-devices
    • First observedsend-command
    • First observedupdate-config
Deploy Server
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

C2.1/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: get-device retrieves a single device, list-devices lists multiple devices, send-command sends commands to devices, and update-config updates device configurations. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

All tool names follow a consistent verb-noun pattern with hyphen separation (e.g., get-device, list-devices, send-command, update-config). The naming is uniform and predictable across all tools.

Tool Count5/5

With 4 tools, this server is well-scoped for managing NodeMCU devices. Each tool serves a distinct and essential function, and the count is appropriate for the apparent scope of device management.

Completeness4/5

The tools cover core CRUD-like operations for device management: listing, retrieving, commanding, and configuring. A minor gap might be the absence of a delete-device or create-device tool, but the existing set supports most common workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches