Thingsboard MCP

🚀 ThingsBoard MCP Server

ThingsBoard MCP Server 为大语言模型（LLMs）和 AI 代理提供了一个自然语言接口，使其能够与 ThingsBoard IoT 平台进行交互，实现对平台内数据的查询、分析和管理等操作。

🔍 目录

• 概述
• 要求
• 特性
  • 实体操作
  • 遥测管理
  • 关系管理
  • 告警管理
  • 系统管理
• 快速开始指南
• 安装
  • Docker 镜像安装
  • 源码构建安装
• 客户端配置
  • 二进制配置
  • Docker 配置
• 环境变量
• 可用工具
  • 设备工具
  • 资产工具
  • 客户工具
  • 用户工具
  • 告警工具
  • 实体组工具
  • 关系工具
  • 遥测工具
  • 管理工具

概述

ThingsBoard MCP Server 为大语言模型（LLMs）和 AI 代理提供了一个 自然语言接口，用于与 ThingsBoard IoT 平台进行交互。

你可以提出诸如“获取我所有类型为 '空气质量传感器' 的设备”之类的问题，并获得结构化的结果：

你可以请求在 ThingsBoard 中模拟或保存时间序列数据：

或者，你可以要求它分析你的时间序列数据，以查找异常、峰值或数据缺口：

此服务器实现了 模型上下文协议（MCP），该协议使 AI 系统能够通过自然语言命令访问和操作 ThingsBoard 中的数据。通过这种集成，你可以：

• 使用对话式语言查询实体（设备、资产、客户等）数据和遥测信息
• 通过 AI 助手管理实体
• 使用 AI 工具分析 IoT 数据并生成报告
• 通过 AI 驱动的工作流自动化 ThingsBoard 操作

该服务器可以与 MCP 客户端（如 Claude Desktop、Cursor 以及其他支持 MCP 协议的 AI 应用程序）无缝集成。

要求

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

• ThingsBoard 实例：一个正在运行的 ThingsBoard 实例，MCP 服务器可以连接到该实例。你可以使用以下任何一种选项：
  • 本地/本地部署社区版：在你自己的 基础设施 上进行自托管安装
  • 本地/本地部署专业版：在你自己的 基础设施 上进行自托管安装
  • ThingsBoard 演示版：可在 demo.thingsboard.io 上使用的免费共享实例
  • ThingsBoard 云服务：在 thingsboard.cloud 上提供的完全托管的云服务
  • 欧洲 ThingsBoard 云服务：在 eu.thingsboard.cloud 上提供的完全托管的云服务
  • ThingsBoard Edge 实例：已 启动并运行
• 认证凭证：在 ThingsBoard 实例上具有适当权限的有效用户名和密码

快速开始指南

1. 配置 MCP 客户端：将 ThingsBoard MCP 服务器添加到你的客户端配置中（请参阅 客户端配置）
2. 开始使用自然语言：通过 MCP 客户端开始与你的 ThingsBoard 实例进行交互

特性

实体操作

• 设备：查看设备详细信息、凭证、配置文件，并管理设备关系
• 资产：查看和管理资产、资产配置文件以及资产关系
• 客户：访问客户信息、标题，并管理客户关系
• 用户：管理用户、令牌、激活链接以及用户分配

遥测管理

• 属性访问：按范围检索任何实体的属性键和值
• 时间序列访问：获取具有各种聚合选项的时间序列数据
• 遥测插入/更新：保存属性或时间序列数据，并可选择设置 TTL（生存时间）

关系管理

通过基于方向的查询发现和导航实体之间的关系。

告警管理

获取特定实体的告警、告警类型和严重性信息。

系统管理

• 系统设置：访问和管理系统管理设置
• 安全设置：查看安全策略和 JWT 配置
• 版本控制：管理存储库和自动提交设置
• 系统信息：检查更新并检索使用统计信息

安装

此 MCP 服务器可与 ThingsBoard IoT 平台或 ThingsBoard Edge 配合使用。安装时需要提供你的 ThingsBoard 实例或 Edge 的 URL 以及有效的凭证。

ThingsBoard 账户

在安装 MCP 服务器之前，请确保你具备以下条件：

1. 可以访问 ThingsBoard 或 Edge 实例
2. 拥有具有足够权限的用户账户
3. 该账户的用户名和密码

Docker 镜像安装

最简单的开始方式是使用 Docker Hub 上预构建的 Docker 镜像。

服务器模式

ThingsBoard MCP 服务器可以在两种不同的模式下运行：

• STDIO 模式（标准输入/输出）：服务器直接通过标准输入/输出流进行通信
• SSE 模式（服务器发送事件）：服务器作为 HTTP 服务器运行，客户端可以连接到该服务器

在 STDIO 模式下运行（默认）

对于 STDIO 模式，必须包含 -i 标志以保持标准输入打开：

docker pull thingsboard/mcp
docker run --rm -i -e THINGSBOARD_URL=<your_thingsboard_url> -e THINGSBOARD_USERNAME=<your_username> -e THINGSBOARD_PASSWORD=<your_password> thingsboard/mcp

在 SSE 模式下运行

在 SSE 模式下，必须使用 -p 标志暴露端口 8000，并显式覆盖默认设置：

docker pull thingsboard/mcp
docker run --rm -p 8000:8000 -e THINGSBOARD_URL=<your_thingsboard_url> -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

源码构建安装

你也可以从源码构建 JAR 文件，并直接运行 ThingsBoard MCP 服务器。

前提条件

• Java 17 或更高版本
• Maven 3.6 或更高版本

构建步骤

1. 克隆此存储库
2. 构建项目：

mvn clean install -DskipTests

3. JAR 文件将位于 target 文件夹中：

./target/thingsboard-mcp-server-1.0.0.jar

4. 使用 JAR 文件运行服务器：

# 对于 STDIO 模式
java -jar ./target/thingsboard-mcp-server-1.0.0.jar

# 对于 SSE 模式
java -Dspring.ai.mcp.server.stdio=false -Dspring.main.web-application-type=servlet -jar ./target/thingsboard-mcp-server-1.0.0.jar

客户端配置

若要在 MCP 客户端启动时将服务器作为容器启动（例如 Claude Desktop），需要在客户端设置中添加相应的配置。

Docker 配置

如果你使用的是 Docker 镜像，请在 claude_desktop_config.json 中使用以下配置：

{
  "mcpServers": {
    "thingsboard": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "THINGSBOARD_URL",
        "-e",
        "THINGSBOARD_USERNAME",
        "-e",
        "THINGSBOARD_PASSWORD",
        "-e",
        "LOGGING_PATTERN_CONSOLE",
        "thingsboard/mcp"
      ],
      "env": {
        "THINGSBOARD_URL": "<thingsboard_url>",
        "THINGSBOARD_USERNAME": "<thingsboard_username>",
        "THINGSBOARD_PASSWORD": "<thingsboard_password>",
        "LOGGING_PATTERN_CONSOLE": ""
      }
    }
  }
}

二进制配置

如果你从源码构建了 JAR 文件，请在 claude_desktop_config.json 中使用以下配置：

{
  "mcpServers": {
    "thingsboard": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/thingsboard-mcp-server-1.0.0.jar"
      ],
      "env": {
        "THINGSBOARD_URL": "<thingsboard_url>",
        "THINGSBOARD_USERNAME": "<thingsboard_username>",
        "THINGSBOARD_PASSWORD": "<thingsboard_password>",
        "LOGGING_PATTERN_CONSOLE": ""
      }
    }
  }
}

环境变量

MCP 服务器需要以下环境变量才能连接到你的 ThingsBoard 实例：

这些变量可以通过以下方式设置：

• 直接通过 Docker 命令行使用 -e 标志
• 或者通过 MCP 客户端设置中的 env 配置块

可用工具

ThingsBoard MCP 服务器提供了广泛的工具，可以通过自然语言命令使用。这些工具按类别进行组织。

设备工具

资产工具

客户工具

用户工具

告警工具

实体组工具

关系工具

遥测工具

管理工具