ThingsBoard MCP 服务器完整教程

项目概述

​​ThingsBoard MCP Server​​ 是一个创新的开源项目，它作为​​模型上下文协议（MCP）服务器​​，为大型语言模型（如Claude、GPT等）提供与ThingsBoard物联网平台交互的自然语言接口。通过这个项目，AI助手可以直接使用自然语言来查询和管理您的物联网设备、资产、遥测数据等。

核心价值

• ​​自然语言交互​​：用对话方式管理物联网平台
• ​​AI驱动自动化​​：通过AI助手自动化ThingsBoard运维任务
• ​​无缝集成​​：支持主流MCP客户端（Claude Desktop、Cursor等）
• ​​全面覆盖​​：支持ThingsBoard所有核心功能

功能特性

🚀 实体操作管理

• ​​设备管理​​：创建、删除、查询设备信息和管理凭证
• ​​资产管理​​：完整的资产生命周期管理
• ​​客户管理​​：客户信息管理和权限控制
• ​​用户管理​​：用户账户和令牌管理

📊 遥测数据处理

• ​​实时数据访问​​：获取最新的传感器读数
• ​​历史数据分析​​：查询特定时间范围的数据
• ​​数据写入​​：保存新的遥测数据和属性
• ​​聚合分析​​：支持多种数据聚合方式

🔗 关系网络管理

• ​​关系建立​​：创建实体间的关联关系
• ​​关系查询​​：基于方向的关系导航和发现
• ​​拓扑分析​​：分析实体间的连接网络

⚠️ 智能报警系统

• ​​报警创建​​：基于条件自动创建报警
• ​​报警查询​​：按严重程度、状态筛选报警
• ​​趋势分析​​：识别报警模式和趋势

快速开始指南

环境要求

在开始之前，请确保您具备以下条件：

安装方法选择

方法一：Docker部署（推荐）

​​STDIO模式​​（标准输入输出）：

docker pull thingsboard/mcp
docker run –rm -i \\
-e THINGSBOARD_URL=https://your-instance.thingsboard.cloud \\
-e THINGSBOARD_USERNAME=your-username \\
-e THINGSBOARD_PASSWORD=your-password \\
thingsboard/mcp

​​SSE模式​​（服务器发送事件）：

docker run –rm -p 8000:8000 \\
-e THINGSBOARD_URL=https://your-instance.thingsboard.cloud \\
-e THINGSBOARD_USERNAME=your-username \\
-e THINGSBOARD_PASSWORD=your-password \\
-e SPRING_AI_MCP_SERVER_STDIO=false \\
-e SPRING_WEB_APPLICATION_TYPE=servlet \\
thingsboard/mcp

方法二：二进制文件部署

# 下载最新版本
wget https://github.com/thingsboard/thingsboard-mcp/releases/download/v2.0.0/thingsboard-mcp-server-2.0.0.jar

# 运行服务器
java -jar thingsboard-mcp-server-2.0.0.jar

方法三：源码编译部署

# 克隆仓库
git clone https://github.com/thingsboard/thingsboard-mcp.git
cd thingsboard-mcp

# 编译项目
mvn clean install -DskipTests

# 运行服务器
java -jar target/thingsboard-mcp-server-2.0.0.jar

客户端配置详解

Claude Desktop配置

​​Docker方式配置​​ (claude_desktop_config.json)：

{
"mcpServers": {
"thingsboard": {
"command": "docker",
"args": [
"run", "-i", "–rm",
"-e", "THINGSBOARD_URL",
"-e", "THINGSBOARD_USERNAME",
"-e", "THINGSBOARD_PASSWORD",
"thingsboard/mcp"
],
"env": {
"THINGSBOARD_URL": "https://your-instance.thingsboard.cloud",
"THINGSBOARD_USERNAME": "your-username",
"THINGSBOARD_PASSWORD": "your-password"
}
}
}
}

​​JAR文件方式配置​​：

{
"mcpServers": {
"thingsboard": {
"command": "java",
"args": [
"-jar",
"/path/to/thingsboard-mcp-server-2.0.0.jar"
],
"env": {
"THINGSBOARD_URL": "https://your-instance.thingsboard.cloud",
"THINGSBOARD_USERNAME": "your-username",
"THINGSBOARD_PASSWORD": "your-password"
}
}
}
}

环境变量配置

工具功能详解

设备管理工具集

​​核心功能​​：

• saveDevice – 创建/更新设备配置
• getDeviceById – 按ID精确查询设备
• getTenantDevices – 获取租户下所有设备
• getDeviceCredentialsByDeviceId – 获取设备访问令牌

​​使用示例​​：

"创建名为'车间温度传感器'的设备，类型为'温度监测'"

资产管理工具集

• saveAsset – 资产管理
• getCustomerAssets – 客户资产查询
• getAssetsByEntityGroupId – 分组资产管理

数据查询工具集

​​遥测数据工具​​：

• getAttributes – 获取设备属性
• getTimeseries – 查询时间序列数据
• getLatestTimeseries – 获取最新数据点

​​高级查询​​：

• findEntityDataByEntityTypeFilter – 按类型筛选
• findEntityDataByRelationsQueryFilter – 关系查询
• countByDeviceTypeFilter – 统计分析

报警管理工具集

• saveAlarm – 创建报警规则
• getAlarms – 报警信息查询
• getHighestAlarmSeverity – 最高严重度报警

实际应用场景

场景一：设备监控与查询

"查询所有温度传感器在过去24小时内的平均温度，并找出异常值"

场景二：资产关系分析

"显示与'生产车间'资产相关的所有设备及其状态"

场景三：自动化运维

"为所有离线设备创建报警，并通知相关运维人员"

场景四：数据分析报告

"生成本周设备运行报告，包括正常运行时间、故障次数和数据质量分析"

高级配置技巧

性能优化配置

# 增加JVM内存配置
java -Xmx2g -Xms1g -jar thingsboard-mcp-server-2.0.0.jar

# 调整日志级别减少IO
-Dlogging.level.com.thingsboard=WARN

安全配置建议

# 使用TLS加密连接
-Dserver.ssl.enabled=true
-Dserver.ssl.key-store=keystore.p12

# 配置访问白名单
-Dspring.security.allowed-ips=192.168.1.0/24

故障排除指南

常见问题解决

​​连接问题​​：

# 检查网络连通性
ping your-thingsboard-instance

# 验证证书有效性
openssl s_client -connect your-instance:443

​​认证失败​​：

• 确认用户名密码正确
• 检查用户权限设置
• 验证租户/客户范围权限

​​性能问题​​：

• 监控服务器资源使用情况
• 调整查询时间范围避免大数据量
• 使用分页查询大结果集

日志分析

# 查看详细日志
tail -f logs/thingsboard-mcp.log

# 启用调试模式
-Dlogging.level.com.thingsboard=DEBUG

最佳实践建议

社区与支持

• ​​GitHub仓库​​：
• ​​问题反馈​​：通过GitHub Issues报告问题
• ​​贡献指南​​：参考CONTRIBUTING.md参与开发
• ​​版本更新​​：关注Re页面获取最新版本

总结

ThingsBoard MCP Server极大地简化了物联网平台的管理复杂度，通过自然语言接口让AI助手成为您的物联网运维专家。无论是设备监控、数据分析还是自动化运维，都能通过简单的对话命令完成。

开始您的AI驱动物联网管理之旅，体验智能化的ThingsBoard操作新时代！