ThingsBoard MCP 服务器完整教程
项目概述
ThingsBoard MCP Server 是一个创新的开源项目，它作为模型上下文协议（MCP）服务器，为大型语言模型（如Claude、GPT等）提供与ThingsBoard物联网平台交互的自然语言接口。通过这个项目，AI助手可以直接使用自然语言来查询和管理您的物联网设备、资产、遥测数据等。
核心价值
- 自然语言交互：用对话方式管理物联网平台
- AI驱动自动化：通过AI助手自动化ThingsBoard运维任务
- 无缝集成：支持主流MCP客户端（Claude Desktop、Cursor等）
- 全面覆盖：支持ThingsBoard所有核心功能
功能特性
🚀 实体操作管理
- 设备管理：创建、删除、查询设备信息和管理凭证
- 资产管理：完整的资产生命周期管理
- 客户管理：客户信息管理和权限控制
- 用户管理：用户账户和令牌管理
📊 遥测数据处理
- 实时数据访问：获取最新的传感器读数
- 历史数据分析：查询特定时间范围的数据
- 数据写入：保存新的遥测数据和属性
- 聚合分析：支持多种数据聚合方式
🔗 关系网络管理
- 关系建立：创建实体间的关联关系
- 关系查询：基于方向的关系导航和发现
- 拓扑分析：分析实体间的连接网络
⚠️ 智能报警系统
- 报警创建：基于条件自动创建报警
- 报警查询：按严重程度、状态筛选报警
- 趋势分析：识别报警模式和趋势
快速开始指南
环境要求
在开始之前，请确保您具备以下条件：
-
ThingsBoard实例（任选其一）：
- ThingsBoard社区版（自托管）
- ThingsBoard专业版（自托管）
- ThingsBoard Cloud（云端服务）
- ThingsBoard演示实例（demo.thingsboard.io）
- ThingsBoard Edge实例
-
认证凭证：
- 有效的用户名和密码
- 相应的操作权限
-
运行环境：
- Docker环境（推荐）
- 或Java 17+运行环境
安装方法选择
方法一：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"
}
}
}
}
环境变量配置
| 变量名 | 描述 | 示例值 | 必需 |
|---|---|---|---|
THINGSBOARD_URL | ThingsBoard实例URL | https://demo.thingsboard.io | ✅ |
THINGSBOARD_USERNAME | 用户名 | tenant@thingsboard.org | ✅ |
THINGSBOARD_PASSWORD | 密码 | your-password | ✅ |
THINGSBOARD_LOGIN_INTERVAL_SECONDS | 会话刷新间隔 | 1800 | ❌ |
SPRING_AI_MCP_SERVER_STDIO | STDIO模式开关 | true | ❌ |
SERVER_PORT | HTTP服务端口 | 8080 | ❌ |
工具功能详解
设备管理工具集
核心功能：
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
最佳实践建议
- 权限管理：为MCP服务创建专用账户，限制最小必要权限
- 查询优化：使用合适的时间范围和分页设置
- 错误处理：实现重试机制处理临时网络问题
- 监控告警：设置服务器健康状态监控
- 备份策略：定期备份重要配置和数据
社区与支持
- GitHub仓库：
- 问题反馈：通过GitHub Issues报告问题
- 贡献指南：参考CONTRIBUTING.md参与开发
- 版本更新：关注Re页面获取最新版本
总结
ThingsBoard MCP Server极大地简化了物联网平台的管理复杂度，通过自然语言接口让AI助手成为您的物联网运维专家。无论是设备监控、数据分析还是自动化运维，都能通过简单的对话命令完成。
开始您的AI驱动物联网管理之旅，体验智能化的ThingsBoard操作新时代！
