MCP 服务器

• Overview
• 要求
• 快速开始指南
• 功能特性
  • 实体操作
  • 遥测管理
  • 关系
  • 告警
  • 管理
• 安装
  • ThingsBoard Account
  • Docker Image
    • Server Modes
    • Running in STDIO Mode (Default)
    • Running in SSE Mode
  • Build from Sources
    • Prerequisites
    • Build Steps
• Client Configuration
  • Docker Configuration
  • 二进制配置
• 环境变量
• 可用工具
  • 设备工具
  • 资产工具
  • 客户工具
  • 用户工具
  • 告警工具
  • 实体组工具
  • 关系工具
  • 遥测工具
  • 管理工具

Overview

ThingsBoard MCP Server为LLM和AI代理与ThingsBoard物联网平台交互提供自然语言界面。

该服务器实现了Model Context Protocol (MCP)，使AI系统可通过自然语言命令访问和操作ThingsBoard中的数据。通过该集成，您可以：

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

服务器可与支持MCP协议的Claude Desktop、Cursor及其他AI应用无缝集成。

要求

开始前请确保具备以下条件：

• ThingsBoard Edge instance up and running

• 认证凭据 - 在ThingsBoard实例上具有相应权限的有效用户名和密码

请记下ThingsBoard URL、用户名和密码 - 后续步骤中将以your_thingsboard_url、your_username和your_password使用。

快速开始指南

1. 配置MCP客户端：将ThingsBoard MCP服务器添加到客户端配置（见客户端配置）
2. 开始使用自然语言：通过MCP客户端与ThingsBoard实例交互

功能特性

实体操作

• 设备：查看设备详情、凭据、配置并管理设备关系
• 资产：查看并管理资产、资产配置和资产关系
• 客户：访问客户信息、标题并管理客户关系
• 用户：管理用户、令牌、激活链接和用户分配

遥测管理

• 属性访问：按作用域获取任意实体的属性键和值
• 时序数据访问：获取支持多种聚合选项的时序数据
• 遥测插入/更新：保存属性或时序数据，支持可选TTL设置

关系

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

告警

获取特定实体的告警、告警类型及严重程度信息。

管理

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

安装

本MCP服务器与ThingsBoard Edge配合使用。安装需提供ThingsBoard Edge实例URL及有效凭据。

ThingsBoard Account

安装MCP服务器前请确保：

• 能访问ThingsBoard Edge实例

• 具有足够权限的用户账户
• 该账户的用户名和密码

Docker Image

建议使用Docker Hub上的预构建Docker镜像快速开始。

Server Modes

ThingsBoard MCP Server支持两种运行模式：

• STDIO Mode（标准输入/输出）：服务器通过标准输入/输出流直接通信
• SSE Mode（Server-Sent Events）：服务器作为HTTP服务运行，供客户端连接

Running in STDIO Mode (Default)

STDIO模式下，必须使用 -i 参数保持stdin打开：

1
2
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

Running in SSE Mode

SSE模式下，需使用 -p 参数暴露8000端口并显式覆盖默认设置：

1
2
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

Build from Sources

也可源码安装JAR并直接运行ThingsBoard MCP Server。

Prerequisites

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

Build Steps

• 克隆仓库
• 构建项目：

1
mvn clean install -DskipTests

• JAR文件将生成于target目录：

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

• 使用JAR运行服务器：

1
2
# For STDIO Mode
java -jar ./target/thingsboard-mcp-server-1.0.0.jar

1
2
# For SSE Mode
java -Dspring.ai.mcp.server.stdio=false Dspring.main.web-application-type=servlet -jar ./target/thingsboard-mcp-server-1.0.0.jar

Client Configuration

若要在MCP客户端启动时（如Claude Desktop）以容器方式启动服务器，需在客户端设置中添加相应配置。

Docker Configuration

若使用Docker镜像，请在 claude_desktop_config.json 中使用如下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "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 中使用如下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "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 Server提供多种可通过自然语言命令使用的工具。按类别组织如下。

设备工具

资产工具

客户工具

用户工具

告警工具

实体组工具

关系工具

遥测工具

管理工具