ThingsBoard MCP 服务器完整教程

项目概述

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

核心价值

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

功能特性

🚀 实体操作管理

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

📊 遥测数据处理

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

🔗 关系网络管理

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

⚠️ 智能报警系统

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

快速开始指南

环境要求

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

1. ​​ThingsBoard实例​​（任选其一）：

   • ThingsBoard社区版（自托管）
   • ThingsBoard专业版（自托管）
   • ThingsBoard Cloud（云端服务）
   • ThingsBoard演示实例（demo.thingsboard.io）
   • ThingsBoard Edge实例

2. ​​认证凭证​​：

   • 有效的用户名和密码
   • 相应的操作权限

3. ​​运行环境​​：

   • 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"
      }
    }
  }
}

环境变量配置

工具功能详解

设备管理工具集

​​核心功能​​：

• 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

最佳实践建议

1. ​​权限管理​​：为MCP服务创建专用账户，限制最小必要权限
2. ​​查询优化​​：使用合适的时间范围和分页设置
3. ​​错误处理​​：实现重试机制处理临时网络问题
4. ​​监控告警​​：设置服务器健康状态监控
5. ​​备份策略​​：定期备份重要配置和数据

社区与支持

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

总结

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

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