JinDaGe - thingsboard-mcp MCP Details

article

README

🚀 ThingsBoard MCP Server

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

🔍 目录

概述
要求
特性
快速开始指南
安装
- Docker 镜像安装
- 源码构建安装
客户端配置
- 二进制配置
- Docker 配置
环境变量
可用工具

概述

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

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

你可以请求在 ThingsBoard 中模拟或保存时间序列数据： Generate Sample Data Example Generated Data In ThingsBoard

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

此服务器实现了模型上下文协议（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 实例上具有适当权限的有效用户名和密码

快速开始指南

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

特性

实体操作

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

遥测管理

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

关系管理

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

告警管理

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

系统管理

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

安装

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

ThingsBoard 账户

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

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

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 或更高版本

构建步骤

克隆此存储库
构建项目：

mvn clean install -DskipTests

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

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

使用 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 实例： | 变量 | 描述 | 默认值 | |------|------|---------| | THINGSBOARD_URL | ThingsBoard 实例的基础 URL | 无 | | THINGSBOARD_USERNAME | 用于与 ThingsBoard 进行认证的用户名 | 无 | | THINGSBOARD_PASSWORD | 用于与 ThingsBoard 进行认证的密码 | 无 | | THINGSBOARD_LOGIN_INTERVAL_SECONDS | 登录会话刷新间隔（秒） | 1800 | | SPRING_WEB_APPLICATION_TYPE | Spring 应用程序类型（none 或 servlet） | none | | SPRING_AI_MCP_SERVER_STDIO | 启用/禁用标准输入/输出通信 | true | | SPRING_AI_MCP_SERVER_SSE_ENDPOINT | 服务器发送事件（SSE）端点 URL | /sse | | SPRING_AI_MCP_SERVER_SSE_MESSAGE_ENDPOINT | 服务器发送事件消息端点 URL | /mcp/message | | SERVER_PORT | HTTP 服务器端口号 | 8080 |

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

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

可用工具

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

设备工具

| 工具 | 描述 | |------|-------------| | getDeviceById | 根据提供的设备 ID 获取设备对象 | | getDeviceCredentialsByDeviceId | 根据设备 ID 获取设备凭证。如果在设备创建时未指定任何凭证，平台将生成随机的 'ACCESS_TOKEN' 凭证 | | getTenantDevices | 返回租户拥有的设备页面 | | getTenantDevice | 根据设备名称获取租户设备。设备名称是设备的唯一属性 | | getCustomerDevices | 返回分配给客户的设备对象页面 | | getUserDevices | 返回当前用户可用的设备对象页面 | | getDevicesByIds | 根据 ID 获取设备。请求的设备必须由租户拥有或分配给客户 | | getDevicesByEntityGroupId | 返回属于指定实体组 ID 的设备对象页面 |

资产工具

| 工具 | 描述 | |------|-------------| | getAssetById | 根据提供的资产 ID 获取资产对象 | | getTenantAssets | 返回租户拥有的资产页面 | | getTenantAsset | 根据资产名称获取租户资产。资产名称是资产的唯一属性 | | getCustomerAssets | 返回分配给客户的资产对象页面 | | getUserAssets | 返回当前用户可用的资产对象页面 | | getAssetsByIds | 根据 ID 获取资产。请求的资产必须由租户拥有或分配给客户 | | getAssetsByEntityGroupId | 返回属于指定实体组 ID 的资产对象页面 |

客户工具

| 工具 | 描述 | |------|-------------| | getCustomerById | 根据提供的客户 ID 获取客户对象 | | getCustomers | 返回租户拥有的客户页面 | | getTenantCustomer | 根据客户标题获取客户 | | getUserCustomers | 返回用户可用的客户页面 | | getCustomersByEntityGroupId | 返回属于指定实体组 ID 的客户对象页面 |

用户工具

| 工具 | 描述 | |------|-------------| | getUserById | 根据提供的用户 ID 获取用户对象 | | getUsers | 返回租户或客户拥有的用户页面 | | getTenantAdmins | 返回分配给指定租户的租户管理员用户页面 | | getCustomerUsers | 返回分配给指定客户的用户页面 | | getAllCustomerUsers | 返回当前租户中具有 'CUSTOMER_USER' 权限的用户页面 | | getUsersForAssign | 返回可以分配给提供的告警 ID 的用户数据对象页面 | | getUsersByEntityGroupId | 返回属于指定实体组 ID 的用户对象页面 |

告警工具

| 工具 | 描述 | |------|-------------| | getAlarmById | 根据提供的告警 ID 获取告警对象 | | getAlarmInfoById | 根据提供的告警 ID 获取告警信息对象 | | getAlarms | 获取所选实体的告警页面 | | getAllAlarms | 获取属于当前用户所有者的告警页面 | | getHighestAlarmSeverity | 根据起源者和可选的状态过滤器获取最高告警严重性 | | getAlarmTypes | 根据租户拥有或分配给客户的告警获取唯一告警类型集合 |

实体组工具

| 工具 | 描述 | |------|-------------| | getEntityGroupById | 根据提供的实体组 ID 获取实体组对象 | | getEntityGroupsByType | 根据提供的实体类型获取实体组信息对象列表 | | getEntityGroupByOwnerAndNameAndType | 根据提供的所有者、类型和名称获取实体组对象 | | getEntityGroupsByOwnerAndType | 根据提供的所有者 ID 和实体类型获取实体组信息对象列表 | | getEntityGroupsForEntity | 返回包含指定实体 ID 的组列表 | | getEntityGroupsByIds | 根据提供的实体组 ID 列表获取实体组信息对象列表 |

关系工具

| 工具 | 描述 | |------|-------------| | getRelation | 如果存在，则返回两个指定实体之间的关系对象 | | findByFrom | 根据 'from' 方向返回指定实体的关系对象列表 | | findInfoByFrom | 根据 'from' 方向返回指定实体的关系信息对象列表 | | findByTo | 根据 'to' 方向返回指定实体的关系对象列表 | | findInfoByTo | 根据 'to' 方向返回指定实体的关系信息对象列表 |

遥测工具

| 工具 | 描述 | |------|-------------| | getAttributeKeys | 获取指定实体的所有属性键 | | getAttributeKeysByScope | 获取指定实体和范围的所有属性键 | | getAttributes | 获取指定实体的属性 | | getAttributesByScope | 获取指定实体和范围的属性 | | getTimeseriesKeys | 获取指定实体的所有时间序列键 | | getLatestTimeseries | 获取指定实体和键的最新时间序列值 | | getTimeseries | 获取指定实体、键和时间范围的时间序列数据 | | saveDeviceAttributes | 保存设备属性 | | saveEntityAttributesV1 | 保存实体属性（版本 1） | | saveEntityAttributesV2 | 保存实体属性（版本 2） | | saveEntityTelemetry | 保存实体遥测数据 | | saveEntityTelemetryWithTTL | 保存具有生存时间（TTL）的实体遥测数据 |

管理工具

| 工具 | 描述 | |------|-------------| | getAdminSettings | 使用指定的字符串键获取系统管理设置对象 | | getSecuritySettings | 获取包含密码策略、锁定限制等的安全设置对象 | | getSystemInfo | 获取系统的主要信息 | | getUsageInfo | 检索当前租户的使用统计信息 |

thingsboard-mcp