AIRIOT MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AIRIOT MCP Server list all devices that are currently online"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | 描述 |
| 数据表列表 |
| 数据表详情 |
| 表记录列表 |
| 设备列表 |
| 设备详情 |
| 最新数据 |
| 在线统计 |
Prompts(提示词模板)
预定义的常用查询模板:
模板名 | 描述 |
| 列出数据表 |
| 获取表结构 |
| 查询设备列表 |
| 获取实时数据 |
| 获取历史趋势 |
| 设备在线摘要 |
| 查询告警 |
| 创建设备 |
| 更新设备状态 |
可用工具
表管理
工具名 | 描述 |
| 查询数据表列表 |
| 根据ID查询单个表 |
| 创建新数据表 |
| 更新表信息 |
| 删除数据表 |
记录管理
工具名 | 描述 |
| 查询表记录列表 |
| 根据ID查询单条记录 |
| 创建新记录 |
| 更新记录 |
| 删除单条记录 |
| 批量删除记录 |
属性点查询
工具名 | 描述 |
| 查询表的属性点定义 |
| 查询记录的属性点 |
时序数据
工具名 | 描述 |
| 查询最新数据 |
| 查询历史时序数据 |
告警管理
工具名 | 描述 |
| 查询告警列表 |
| 查询告警详情 |
| 确认告警 |
| 解除告警 |
文件管理
工具名 | 描述 |
| 上传文件 |
| 获取文件信息 |
| 删除文件 |
设备控制
工具名 | 描述 |
| 发送控制命令 |
| 批量发送控制命令 |
报表管理
工具名 | 描述 |
| 查询报表列表 |
| 查询报表详情 |
| 执行报表生成 |
| 创建报表 |
| 更新报表 |
| 删除报表 |
用户管理
工具名 | 描述 |
| 获取当前用户信息 |
| 获取用户列表 |
使用示例
查询所有数据表
调用 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.jsonAPI 文档
本服务器基于 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 toolsacknowledge_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
Scored across 60 tools
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.
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).
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.
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
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for AI dialogue using various LLM models via AceDataCloud
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to query databases, execute SQL, and manage Metabase resources like dashboards, cards, and collections through natural language.22MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for hubNote, enabling AI assistants to manage workspaces, pages, and data rows via natural language.9 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn 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
- AlicenseNot gradedqualityDmaintenanceMCP server for integrating with Bika.ai platform, enabling AI assistants to perform CRUD operations on databases, manage attachments, and utilize automation and webhooks.1MIT