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 服務器提供了廣泛的工具，可以通過自然語言命令使用。這些工具按類別進行組織。

設備工具

資產工具

客戶工具

用戶工具

告警工具

實體組工具

關係工具

遙測工具

管理工具