Skip to main content
Glama
AIRIOT MCP Server
by sshwsfc

AIRIOT MCP Server

基于 Model Context Protocol (MCP) 的 AIRIOT IoT 平台服务器,为 AI 助手提供完整的 AIRIOT 平台访问能力。

功能特性

核心能力

  • 📊 数据表管理: 查询、创建、更新、删除数据表

  • 📝 记录操作: 对表记录进行 CRUD 操作(含批量)

  • 🏷️ 属性点查询: 查询表和记录的属性点定义

  • 📈 时序数据: 查询设备最新数据和历史数据

  • 📊 统计分析: 设备在线状态统计

MCP 能力支持

  • 🔧 Tools: 30+ 工具接口

  • 📁 Resources: 10+ 资源端点,支持直接读取平台数据作为上下文

  • 💬 Prompts: 12+ 预定义提示词模板

新增功能

  • 🚨 告警管理: 查询、确认、解除告警

  • 📁 文件管理: 上传、下载、删除文件

  • 🎮 设备控制: 发送控制命令

  • 📄 报表管理: 创建、执行、管理报表

  • 👤 用户管理: 查询用户信息

开发体验

  • ⚙️ 配置文件: 支持 .airiotrc.json 配置文件

  • 📝 日志系统: 分级日志,便于调试

  • 🛡️ 错误处理: 完善的错误类型和错误恢复机制

Related MCP server: @hubnote-mcp/server

安装

cd airiot-mcp-server
npm install
npm run build

配置

方式一:配置文件(推荐)

在项目根目录创建 .airiotrc.json 文件:

{
  "baseUrl": "https://your-airiot-server.com",
  "projectId": "your-project-id",
  "token": "your-api-token",
  "timeout": 30000,
  "logLevel": "info",
  "retries": 3
}

可参考 .airiotrc.json.example 文件。

方式二:环境变量

创建 .env 文件或设置以下环境变量:

# AIRIOT 服务器地址(必填)
export AIRIOT_BASE_URL="https://your-airiot-server.com"

# 项目ID(必填)
export AIRIOT_PROJECT_ID="your-project-id"

# 认证方式1: 使用Token(推荐)
export AIRIOT_TOKEN="your-api-token"

# 认证方式2: 使用用户名密码
export AIRIOT_USERNAME="your-username"
export AIRIOT_PASSWORD="your-password"

# 日志级别(可选)
export AIRIOT_LOG_LEVEL="info"

MCP 配置

在 Claude Desktop 配置文件中添加:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "airiot": {
      "command": "node",
      "args": [
        "/path/to/airiot-mcp-server/dist/index.js"
      ],
      "env": {
        "AIRIOT_BASE_URL": "https://your-airiot-server.com",
        "AIRIOT_PROJECT_ID": "your-project-id",
        "AIRIOT_TOKEN": "your-api-token"
      }
    }
  }
}

MCP 能力

Resources(资源)

AI 可以直接读取以下资源作为上下文:

URI

描述

airiot://tables

数据表列表

airiot://tables/{id}

数据表详情

airiot://table/{tableName}/records

表记录列表

airiot://devices

设备列表

airiot://device/{id}

设备详情

airiot://device/{deviceId}/tag/{tagId}/latest

最新数据

airiot://stats/online

在线统计

Prompts(提示词模板)

预定义的常用查询模板:

模板名

描述

list_tables

列出数据表

describe_table

获取表结构

query_devices

查询设备列表

get_realtime_data

获取实时数据

get_history_trend

获取历史趋势

device_online_summary

设备在线摘要

query_alarms

查询告警

create_device

创建设备

update_device_status

更新设备状态

可用工具

表管理

工具名

描述

get_tables

查询数据表列表

get_table_by_id

根据ID查询单个表

create_table

创建新数据表

update_table

更新表信息

delete_table

删除数据表

记录管理

工具名

描述

get_table_records

查询表记录列表

get_record_by_id

根据ID查询单条记录

create_record

创建新记录

update_record

更新记录

delete_record

删除单条记录

batch_delete_records

批量删除记录

属性点查询

工具名

描述

get_table_tags

查询表的属性点定义

get_record_tags

查询记录的属性点

时序数据

工具名

描述

get_latest_data

查询最新数据

get_history_data

查询历史时序数据

告警管理

工具名

描述

get_alarms

查询告警列表

get_alarm_by_id

查询告警详情

acknowledge_alarm

确认告警

resolve_alarm

解除告警

文件管理

工具名

描述

upload_file

上传文件

get_file_info

获取文件信息

delete_file

删除文件

设备控制

工具名

描述

send_control_command

发送控制命令

send_batch_control_commands

批量发送控制命令

报表管理

工具名

描述

get_reports

查询报表列表

get_report_by_id

查询报表详情

execute_report

执行报表生成

create_report

创建报表

update_report

更新报表

delete_report

删除报表

用户管理

工具名

描述

get_current_user

获取当前用户信息

get_users

获取用户列表

使用示例

查询所有数据表

调用 get_tables 工具,参数:
{
  "limit": 50,
  "sort": { "createTime": -1 }
}

查询特定表的记录

调用 get_table_records 工具,参数:
{
  "tableName": "device",
  "filter": { "status": "online" },
  "limit": 100
}

创建新表

创建表需要提供完整的 schema 定义:

调用 create_table 工具,参数:
{
  "id": "my_table",
  "title": "我的数据表",
  "showField": "name",
  "schema": {
    "form": ["name", "status", "createTime"],
    "key": "myTable",
    "listFields": ["name", "status", "createTime"],
    "name": "myTable",
    "properties": {
      "name": {
        "type": "string",
        "key": "name",
        "title": "名称",
        "fieldType": "input",
        "listFields": true,
        "createShow": true,
        "editShow": true,
        "need": true,
        "unique": true
      },
      "status": {
        "type": "string",
        "key": "status",
        "title": "状态",
        "fieldType": "input",
        "listFields": true,
        "createShow": true,
        "editShow": true,
        "need": false
      },
      "createTime": {
        "type": "string",
        "key": "createTime",
        "title": "创建时间",
        "fieldType": "datePicker",
        "listFields": true,
        "createShow": false,
        "editShow": false,
        "disabled": true,
        "format": "datetime"
      }
    },
    "required": ["name"],
    "title": "我的表",
    "type": "object"
  }
}

查询告警

调用 get_alarms 工具,参数:
{
  "level": "critical",
  "status": "active",
  "limit": 50
}

发送设备控制命令

调用 send_control_command 工具,参数:
{
  "deviceId": "设备ID",
  "tagName": "control_tag",
  "value": 1
}

执行报表

调用 execute_report 工具,参数:
{
  "id": "报表ID",
  "parameters": {
    "startDate": "2024-01-01",
    "endDate": "2024-12-31"
  }
}

CLI 使用

项目同时提供 CLI 工具 airiot,用于命令行操作 AIRIOT 平台。

安装

npm install -g .
# 或使用 npx
npx @airiot/mcp-server

配置

首次使用需要登录:

airiot login --url https://your-airiot-server.com --project your-project-id

或使用 Token:

airiot login --url https://your-airiot-server.com --project your-project-id --token your-token

常用命令

# 查看帮助
airiot --help

# 查询数据表
airiot tables
airiot table <table-id>

# 查询记录
airiot records <table-id>
airiot record <table-id> <record-id>

# 查询报警
airiot warnings
airiot warnings confirm <warning-id>
airiot warnings resolve <warning-id>

# 查询最新数据
airiot data-latest --device <device-id> --tag <tag-id>

# 查询历史数据
airiot data-history --device <device-id> --tag <tag-id> --start <timestamp> --end <timestamp>

# 设备控制
airiot control-send --device <device-id> --tag <tag-name> --value <value>

# 查看配置
airiot config

# 登出
airiot logout

更多命令请查看 airiot --help。

测试

项目包含完整的测试套件,使用 Vitest 进行测试。

# 运行所有测试
npm test

# 运行测试并监听文件变化
npm test -- --watch

# 运行测试并生成覆盖率报告
npm run test:coverage

# 运行测试一次(不监听)
npm run test:run

测试覆盖范围:

  • ✅ 所有 CLI 命令功能测试

  • ✅ 工具函数测试

  • ✅ 配置管理测试

  • ✅ API 客户端 mock 测试

开发

# 安装依赖
npm install

# 开发模式(自动编译)
npm run dev

# 构建
npm run build

# 运行 MCP 服务器
npm start

# 运行 CLI
npm run cli

项目结构

mcp-server/
├── src/
│   ├── index.ts           # MCP 服务器入口
│   ├── airiot-api.ts      # AIRIOT API 客户端
│   ├── types.ts           # 类型定义
│   ├── config.ts          # 配置管理
│   ├── logger.ts          # 日志系统
│   ├── errors.ts          # 错误处理
│   ├── tools/             # MCP 工具
│   ├── resources/         # MCP 资源
│   ├── prompts/           # MCP 提示词
│   └── cli/               # CLI 工具
│       ├── index.ts       # CLI 入口
│       ├── config.ts      # CLI 配置管理
│       ├── formatter.ts   # 输出格式化
│       ├── utils.ts       # CLI 工具函数
│       ├── commands/      # CLI 命令模块
│       │   ├── warning.ts # 报警管理命令
│       │   ├── tables.ts  # 表管理命令
│       │   ├── records.ts # 记录管理命令
│       │   ├── tags.ts    # 属性点查询命令
│       │   ├── data.ts    # 时序数据命令
│       │   ├── stats.ts   # 统计命令
│       │   ├── files.ts   # 文件管理命令
│       │   ├── control.ts # 设备控制命令
│       │   ├── reports.ts # 报表管理命令
│       │   └── users.ts   # 用户管理命令
│       └── tests/         # 测试工具
├── dist/                  # 编译输出
├── .airiotrc.json.example # 配置示例
├── vitest.config.ts       # 测试配置
└── package.json

API 文档

本服务器基于 AIRIOT API 4.0 文档实现。

主要接口包括:

  • 表管理: /core/t/schema/*

  • 表记录管理: /core/t/{table}/d/*

  • 属性点管理: /core/t/schema/tag/*

  • 时序数据: /api/core/time-series/*

  • 告警管理: /api/alarms/*

  • 文件管理: /api/files/*

  • 设备控制: /api/control/*

  • 报表管理: /api/reports/*

错误处理

服务器实现了完善的错误处理机制:

  • NetworkError: 网络连接错误

  • AuthError: 认证失败(401)

  • NotFoundError: 资源不存在(404)

  • ApiError: API 请求错误(4xx/5xx)

  • ValidationError: 参数验证错误

所有错误都会返回详细的错误信息,包括错误代码和详情。

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request!

Available Tools

60 tools
acknowledge_alarmA

[已废弃] 请使用 update_warning 替代。确认告警,将告警状态从active改为acknowledged

Inputs: id (required), note, userId.

archive_all_warningsB

一键归档所有符合条件的报警

Inputs: no named parameters.

batch_confirm_warningsC

批量确认报警

Inputs: ids (required), note, userId.

batch_delete_recordsC

批量删除表记录

Inputs: tableName (required), ids (required).

create_recordB

在指定表中创建新记录

Inputs: tableName (required), data (required), upsert.

create_reportD

创建新报表

Inputs: name (required), type (required), description, config.

create_tableC

创建新的数据表,需要提供完整的表结构定义(schema)

Inputs: id (required), title (required), schema (required), showField, +1 more.

create_warningB

创建新的报警记录

Inputs: level (required), content (required), ruleId, status, +8 more.

create_warning_cleanB

创建新的报警清除规则

Inputs: name (required), cleanType (required), cleanCondition (required), enable.

create_warning_ruleC

创建新的报警规则

Inputs: name (required), level (required), enable, description, +2 more.

delete_fileD

删除文件

Inputs: id (required).

delete_recordC

删除单条表记录

Inputs: tableName (required), id (required), attachment.

delete_reportC

删除报表

Inputs: id (required).

delete_tableC

删除数据表

Inputs: id (required).

delete_warningC

删除报警记录

Inputs: id (required).

delete_warning_cleanC

删除报警清除规则

Inputs: id (required).

delete_warning_ruleC

删除报警规则

Inputs: id (required).

execute_reportB

执行报表生成,返回报表数据

Inputs: id (required), parameters.

execute_warning_cleanC

立即执行清除规则

Inputs: id (required).

get_alarm_by_idA

[已废弃] 请使用 get_warning_by_id 替代。根据ID查询单个告警的详细信息

Inputs: id (required).

get_alarmsA

[已废弃] 请使用 get_warnings 替代。查询告警列表,支持按级别、状态、时间范围过滤

Inputs: level, status, startTime, endTime, +2 more.

get_archived_warningsB

查询已归档的报警列表

Inputs: filter, sort, limit, skip, +1 more.

get_archive_settingB

获取自动归档设置

Inputs: no named parameters.

get_current_userA

获取当前登录用户的信息

Inputs: no named parameters.

get_file_infoC

获取文件信息

Inputs: id (required).

get_history_dataB

查询设备属性点的历史时序数据

Inputs: deviceTagPairs (required), startTime (required), endTime (required), limit.

get_latest_dataB

查询设备属性点的最新数据

Inputs: deviceTagPairs (required).

get_latest_warningsC

获取最新的报警列表

Inputs: limit.

get_online_statsD

统计数据表下设备的在线状态

Inputs: tableIds (required).

get_record_by_idB

根据ID查询单个表记录的详细信息

Inputs: tableName (required), id (required).

get_record_tagsC

查询表记录的属性点列表

Inputs: tableName (required), recordId (required).

get_report_by_idB

根据ID查询单个报表的详细信息

Inputs: id (required).

get_reportsC

查询报表列表

Inputs: filter, limit.

get_table_by_idA

根据ID查询单个数据表的详细信息

Inputs: id (required).

get_table_recordsB

查询数据表的记录列表,支持过滤、排序、分页和字段投影

Inputs: tableName (required), filter, sort, limit, +3 more.

get_tablesA

查询AIRIOT数据表列表,支持过滤、排序和分页

Inputs: filter, sort, limit, skip.

get_table_tagsA

查询数据表的所有属性点定义

Inputs: tableId (required).

get_usersC

获取用户列表

Inputs: filter, limit.

get_warning_by_idB

根据ID查询单个报警的详细信息

Inputs: id (required).

get_warning_clean_by_idA

根据ID查询单个清除规则的详细信息

Inputs: id (required).

get_warning_cleansC

查询报警清除规则列表

Inputs: filter, sort, limit, skip, +1 more.

get_warning_descriptionsC

获取报警描述列表

Inputs: no named parameters.

get_warning_rule_by_idA

根据ID查询单个报警规则的详细信息

Inputs: id (required).

get_warning_rulesA

查询报警规则列表,支持过滤、排序和分页

Inputs: filter, sort, limit, skip, +1 more.

get_warningsC

查询报警列表,支持按级别、状态、设备、时间范围等过滤

Inputs: filter, sort, limit, skip, +9 more.

get_warning_statisticsA

获取报警统计信息(总数、各级别数量、各状态数量等)

Inputs: no named parameters.

get_warning_timelineB

获取报警时间线数据(指定时间段内的报警趋势)

Inputs: startTime (required), endTime (required), level.

loginB

用户登录,返回 token 和用户信息

Inputs: username (required), password (required), code.

resolve_alarmA

[已废弃] 请使用 update_warning 替代。解除告警,将告警状态改为resolved

Inputs: id (required), note.

restore_archived_warningC

恢复已归档的报警

Inputs: id (required).

send_batch_control_commandsC

批量发送控制命令

Inputs: commands (required).

send_control_commandC

向设备发送控制命令

Inputs: deviceId (required), tagName (required), value (required), timeout.

update_archive_settingC

更新自动归档设置

Inputs: enable, archiveDays, archiveStatus.

update_recordC

更新表记录数据

Inputs: tableName (required), id (required), data (required).

update_reportB

更新报表信息

Inputs: id (required), name, description, config.

update_tableC

更新数据表信息

Inputs: id (required), name, description.

update_warningB

更新报警信息(状态、确认信息等)

Inputs: id (required), status, confirmTime, confirmUser, +3 more.

update_warning_cleanC

更新报警清除规则

Inputs: id (required), name, enable, cleanType, +1 more.

update_warning_ruleC

更新报警规则

Inputs: id (required), name, level, enable, +1 more.

upload_fileB

上传文件到AIRIOT平台

Inputs: filePath (required), filename, mimeType.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.5/5.0

    Scored across 60 tools

    Disambiguation2/5

    Many tools have overlapping purposes, especially around alarms/warnings with both deprecated and current tools (e.g., acknowledge_alarm vs update_warning). Numerous similar warning-related tools (get_warnings, get_latest_warnings, get_archived_warnings) can confuse an agent on which to use.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern using snake_case. However, there are minor inconsistencies: use of 'alarm' in deprecated tools vs 'warning' in current ones, and singular/plural variations (e.g., archive_all_warnings vs restore_archived_warning).

    Tool Count2/5

    With 60 tools, the server covers a very broad scope (user management, tables, reports, warnings, files, device control) making it unwieldy. The number is excessive for a typical MCP server, leading to tool selection challenges.

    Completeness4/5

    The tool set provides comprehensive CRUD and lifecycle operations for tables, records, reports, and warnings, plus additional features like archiving, statistics, and device control. Only minor gaps exist due to the presence of deprecated tools, but functionally the surface is complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to query databases, execute SQL, and manage Metabase resources like dashboards, cards, and collections through natural language.
      22
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to manage LoRaWAN devices on Actility ThingPark, allowing device listing, details, and downlink command sending via natural language.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for integrating with Bika.ai platform, enabling AI assistants to perform CRUD operations on databases, manage attachments, and utilize automation and webhooks.
      1
      MIT