Thingsboard Mcp Server

Name: Thingsboard Mcp Server
Author: thingsboard

本地服务

github.com/thingsboard云与基础设施9935 周前更新

代码仓库

关于 Thingsboard Mcp Server

ThingsBoard MCP Server 将 AI Agent 连接到 ThingsBoard IoT 实例，以操作设备、实体、遥测数据和告警。其工具覆盖数据查询与实体管理，并可配置工具组及 STDIO 或 SSE 传输。

主要功能

01设备、资产、客户和用户管理
02遥测与时间序列数据操作
03告警和实体关系管理
04OTA 软件包处理
05可配置工具组与传输方式

适用场景

01查询 IoT 部署中的设备和遥测数据
02管理告警与实体关系
03为设备分配固件软件包

MCP 相关

该服务向 MCP 客户端提供 120 多种 ThingsBoard 操作工具。支持供本地启动客户端使用的 STDIO，以及面向 HTTP 连接的 SSE。

#thingsboard #iot-platform #monitoring #data-visualization #device-management

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.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": "<LOGGING_PATTERN_CONSOLE>"
      }
    }
  }
}

启动命令

docker run -i --rm -e THINGSBOARD_URL -e THINGSBOARD_USERNAME -e THINGSBOARD_PASSWORD -e LOGGING_PATTERN_CONSOLE thingsboard/mcp

需要配置的环境变量

THINGSBOARD_URL

THINGSBOARD_USERNAME

THINGSBOARD_PASSWORD密钥

LOGGING_PATTERN_CONSOLE

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocithingsboard/mcpstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

ThingsBoard MCP 服务

通过 Model Context Protocol (MCP) 将 AI Agent 连接到你的 ThingsBoard IoT 平台。查询设备、管理实体、分析遥测数据并自动化运维——全部通过自然语言完成。

适用于 Claude Desktop、Cursor、VS Code Copilot、Claude Code，以及任何兼容 MCP 的客户端。

快速开始

你需要一个 ThingsBoard 实例（Cloud、EU Cloud、自托管 CE/PE，或 Edge）以及一个 API key（ThingsBoard 4.3+）或用户名/密码。

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "thingsboard": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "THINGSBOARD_URL", "-e", "THINGSBOARD_API_KEY", "thingsboard/mcp"],
      "env": {
        "THINGSBOARD_URL": "https://thingsboard.cloud",
        "THINGSBOARD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "thingsboard": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "THINGSBOARD_URL", "-e", "THINGSBOARD_API_KEY", "thingsboard/mcp"],
      "env": {
        "THINGSBOARD_URL": "https://thingsboard.cloud",
        "THINGSBOARD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

VS Code Copilot

添加到你的 VS Code settings.json 或 .vscode/mcp.json：

{
  "mcp": {
    "servers": {
      "thingsboard": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "-e", "THINGSBOARD_URL", "-e", "THINGSBOARD_API_KEY", "thingsboard/mcp"],
        "env": {
          "THINGSBOARD_URL": "https://thingsboard.cloud",
          "THINGSBOARD_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Claude Code

claude mcp add thingsboard \
  -e THINGSBOARD_URL=https://thingsboard.cloud \
  -e THINGSBOARD_API_KEY=YOUR_API_KEY \
  -- docker run -i --rm -e THINGSBOARD_URL -e THINGSBOARD_API_KEY thingsboard/mcp

SSE 模式（任何基于 HTTP 的 MCP 客户端）

启动服务：

docker run --rm -p 8000:8000 \
  -e THINGSBOARD_URL=https://thingsboard.cloud \
  -e THINGSBOARD_API_KEY=YOUR_API_KEY \
  -e SPRING_AI_MCP_SERVER_STDIO=false \
  -e SPRING_WEB_APPLICATION_TYPE=servlet \
  thingsboard/mcp

然后将你的 MCP 客户端指向 http://localhost:8000/sse。

旧版认证：如果你的 ThingsBoard 版本低于 4.3，请使用 THINGSBOARD_USERNAME 和 THINGSBOARD_PASSWORD 代替 THINGSBOARD_API_KEY。

你可以做什么

用自然语言提问，从你的 ThingsBoard 实例获取结构化结果：


查询设备和实体	分析时序数据

生成并保存遥测数据	获取异常分析

120+ 个工具，涵盖 10 个工具组：

设备 — 创建、更新、删除、列出，按名称/类型/组搜索
资产 — 增删改查，按租户/客户列出，搜索
客户 — 增删改查，列出，按标题搜索
用户 — 增删改查，列出，管理员/客户用户管理
告警 — 创建、确认、清除、删除，按严重程度查询
遥测 — 读写属性和时序数据，聚合，TTL
关系 — 创建、删除，浏览实体关系
OTA 包 — 上传、下载，将固件/软件分配给设备
实体组（PE）— 管理组，分配/移除实体
实体数据查询 — 跨所有实体类型的复杂筛选查询，支持属性/遥测筛选

安装

Docker（推荐）

docker pull thingsboard/mcp

Docker 镜像支持两种传输模式：

STDIO（默认）— 适用于将服务作为子进程启动的客户端（Claude Desktop、Cursor 等）
SSE — 适用于通过 HTTP 连接的客户端

使用示例请参见快速开始。

下载二进制文件

wget https://github.com/thingsboard/mcp-server/releases/download/v2.1.0/thingsboard-mcp-server-2.1.0.jar

运行方式：

# STDIO mode
java -jar thingsboard-mcp-server-2.1.0.jar

# SSE mode
java -Dspring.ai.mcp.server.stdio=false -Dspring.main.web-application-type=servlet -jar thingsboard-mcp-server-2.1.0.jar

二进制客户端配置

如果你使用 JAR 文件而非 Docker，请在 claude_desktop_config.json 中使用以下配置：

{
  "mcpServers": {
    "thingsboard": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/thingsboard-mcp-server-2.1.0.jar"],
      "env": {
        "THINGSBOARD_URL": "https://thingsboard.cloud",
        "THINGSBOARD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

从源码构建

需要 Java 17+ 和 Maven 3.6+。

git clone https://github.com/thingsboard/mcp-server.git
cd mcp-server
mvn clean install -DskipTests
java -jar target/thingsboard-mcp-server-2.1.0.jar

配置

环境变量

变量	描述	默认值
`THINGSBOARD_URL`	ThingsBoard 实例的基础 URL	必填
`THINGSBOARD_API_KEY`	用于身份验证的 API 密钥（4.3+ 推荐）
`THINGSBOARD_USERNAME`	用于身份验证的用户名（旧版）
`THINGSBOARD_PASSWORD`	用于身份验证的密码（旧版）
`THINGSBOARD_LOGIN_INTERVAL_SECONDS`	会话刷新间隔	`1800`
`HTTP_BIND_ADDRESS`	HTTP 绑定地址（SSE 模式）	`127.0.0.1`
`HTTP_BIND_PORT`	HTTP 端口（SSE 模式）	`8000`
`SPRING_AI_MCP_SERVER_STDIO`	启用 STDIO 传输	`true`
`SPRING_WEB_APPLICATION_TYPE`	STDIO 使用 `none`，SSE 使用 `servlet`	`none`
`SPRING_AI_MCP_SERVER_SSE_ENDPOINT`	SSE 端点路径	`/sse`
`SPRING_AI_MCP_SERVER_SSE_MESSAGE_ENDPOINT`	SSE 消息端点路径	`/mcp/message`

高级：连接与日志

变量	描述	默认值
`THINGSBOARD_CONNECTION_MAX_RETRIES`	最大连接重试次数	`3`
`THINGSBOARD_CONNECTION_RETRY_DELAY_SECONDS`	重试之间的延迟	`5`
`THINGSBOARD_CONNECTION_CONNECT_TIMEOUT_SECONDS`	HTTP 连接超时	`10`
`THINGSBOARD_CONNECTION_READ_TIMEOUT_SECONDS`	HTTP 读取超时	`60`
`LOG_LEVEL_APP`	应用日志级别	`info`
`LOG_LEVEL_TOOLS`	工具执行日志级别	`info`
`LOG_LEVEL_TOOL_RESPONSE`	工具响应日志级别	`info`
`LOGGING_PATTERN_CONSOLE`	Logback 控制台模式	`%d{yyyy-MM-dd HH:mm:ss} \| %-5level \| %logger{1} \| %msg%n`
`LOGGING_CONSOLE_TARGET`	日志输出目标	`System.err`

工具组

该服务提供 120+ 个工具，可能超出某些客户端的上下文限制。禁用你不需要的组：

变量	组	工具数	默认值
`THINGSBOARD_TOOLS_EDQ`	实体数据查询 + 指南	40	`true`
`THINGSBOARD_TOOLS_TELEMETRY`	遥测与属性	11	`true`
`THINGSBOARD_TOOLS_DEVICE`	设备	11	`true`
`THINGSBOARD_TOOLS_ASSET`	资产	8	`true`
`THINGSBOARD_TOOLS_ALARM`	告警	9	`true`
`THINGSBOARD_TOOLS_OTA`	OTA 包	11	`true`
`THINGSBOARD_TOOLS_RELATION`	关系	8	`true`
`THINGSBOARD_TOOLS_CUSTOMER`	客户	7	`true`
`THINGSBOARD_TOOLS_USER`	用户	9	`true`
`THINGSBOARD_TOOLS_GROUP`	实体组（仅 PE）	10	`true`

示例 — 为上下文有限的客户端减少到约 50 个工具：

{
  "env": {
    "THINGSBOARD_TOOLS_EDQ": "false",
    "THINGSBOARD_TOOLS_OTA": "false",
    "THINGSBOARD_TOOLS_GROUP": "false",
    "THINGSBOARD_TOOLS_USER": "false"
  }
}

可用工具

设备工具（11）

工具	描述
`createOrUpsertDevice`	按名称创建或更新设备。大多数设备任务的主要工具。
`saveDevice`	从原始 JSON 创建或更新设备对象。高级工具。
`deleteDevice`	按 id 删除设备。
`getDeviceById`	根据提供的设备 Id 获取设备对象。
`getDeviceCredentialsByDeviceId`	按设备 id 获取设备凭证。
`getTenantDevices`	返回租户拥有的设备分页。
`getTenantDevice`	按名称获取租户设备。
`getCustomerDevices`	返回分配给客户的设备分页。
`getUserDevices` (PE)	返回当前用户可用的设备分页。
`getDevicesByIds`	按 ids 获取设备。
`getDevicesByEntityGroupId` (PE)	返回指定实体组中的设备分页。

资产工具（8）

| 工具 | 描述 | |------|-------------| | `saveAsset` | 创建或更新资产对象。 | | `deleteAsset` | 按 id 删除资产。 | | `getAssetById` | 按 id 获取资产对象。 | | `getTenantAssets` | 返回租户拥有的资产分页。 | | `getTenantAsset` | 按名称获取租户资产。 | | `getCustomerAssets` | 返回分配给客户的资产分页。 | | `getUserAssets` **(PE)** | 返回当前用户可用的资产分页。 | | `getAssetsByEntityGroupId` **(PE)** | 返回指定实体组中的资产分页。 |

客户工具 (7)

工具	描述
`saveCustomer`	创建或更新客户对象。
`deleteCustomer`	按 id 删除客户。
`getCustomerById`	按 id 获取客户对象。
`getCustomers`	返回租户拥有的客户分页。
`getTenantCustomer`	按标题获取客户。
`getUserCustomers` (PE)	返回用户可用的客户分页。
`getCustomersByEntityGroupId` (PE)	返回指定实体组中的客户分页。

用户工具 (9)

工具	描述
`saveUser`	创建或更新用户对象。
`deleteUser`	按 id 删除用户。
`getUserById`	按 id 获取用户对象。
`getUsers`	返回租户或客户拥有的用户分页。
`getTenantAdmins`	返回租户管理员用户分页。
`getCustomerUsers`	返回分配给客户的用户分页。
`getAllCustomerUsers` (PE)	返回当前租户的所有客户用户分页。
`getUsersForAssign`	返回可分配给告警的用户。
`getUsersByEntityGroupId` (PE)	返回指定实体组中的用户分页。

告警工具 (9)

工具	描述
`saveAlarm`	创建或更新告警对象。
`deleteAlarm`	按 id 删除告警。
`ackAlarm`	确认告警。
`clearAlarm`	清除告警。
`getAlarmInfoById`	按 id 获取告警信息（包含发起者名称）。
`getAlarms`	获取所选实体的告警分页。
`getAllAlarms`	获取当前用户所有者的告警分页。
`getHighestAlarmSeverity`	按发起者获取最高告警严重级别。
`getAlarmTypes`	获取唯一告警类型。

OTA 工具 (11)

工具	描述
`saveOtaPackageInfo`	创建或更新 OTA 包信息。
`saveOtaPackageData`	从文件路径上传 OTA 包二进制文件。
`downloadOtaPackage`	将 OTA 包二进制文件下载到本地文件路径。
`getOtaPackageInfoById`	按 id 获取 OTA 包信息。
`getOtaPackageById`	按 id 获取 OTA 包。
`getOtaPackages`	获取 OTA 包（分页）。
`getOtaPackagesByDeviceProfile`	按设备配置文件和类型获取 OTA 包。
`assignOtaPackageToDevice`	为设备分配或清除 OTA 包。
`assignOtaPackageToDeviceProfile`	为设备配置文件分配或清除 OTA 包。
`countByDeviceProfileAndEmptyOtaPackage`	统计未分配 OTA 包的设备数量。
`deleteOtaPackage`	按 id 删除 OTA 包。

关系工具 (8)

| 工具 | 描述 | |------|-------------| | `saveRelation` | 创建或更新关系。 | | `deleteRelation` | 删除两个实体之间的关系。 | | `deleteRelations` | 删除某个实体的所有关系。 | | `getRelation` | 获取两个实体之间的关系。 | | `findInfoByFrom` | 查找从某个实体出发的关系（包含实体名称）。 | | `findByFromWithRelationType` | 按类型筛选，查找从某个实体出发的关系。 | | `findInfoByTo` | 查找指向某个实体的关系（包含实体名称）。 | | `findByToWithRelationType` | 按类型筛选，查找指向某个实体的关系。 |

遥测工具（11）

工具	描述
`getAttributeKeys`	获取某个实体的所有属性键。
`getAttributeKeysByScope`	按作用域获取属性键。
`getAttributes`	获取某个实体的属性。
`getAttributesByScope`	按作用域获取属性。
`getTimeseriesKeys`	获取某个实体的所有时间序列键。
`getLatestTimeseries`	获取最新的时间序列值。
`getTimeseries`	获取某个时间范围内的时间序列数据。
`saveDeviceAttributes`	保存设备属性。
`saveEntityAttributesV2`	保存实体属性。
`saveEntityTelemetry`	保存实体遥测数据。
`saveEntityTelemetryWithTTL`	保存带 TTL 的实体遥测数据。

实体组工具 — 仅 PE（10）

工具	描述
`saveEntityGroup`	创建或更新实体组。
`deleteEntityGroup`	按 id 删除实体组。
`getEntityGroupById`	按 id 获取实体组。
`getEntityGroupsByType`	按实体类型获取实体组。
`getEntityGroupByOwnerAndNameAndType`	按所有者、类型和名称获取实体组。
`getEntityGroupsByOwnerAndType`	按所有者和类型获取实体组。
`getEntityGroupsForEntity`	获取包含指定实体的组。
`getEntityGroupsByIds`	按 ids 获取实体组。
`addEntitiesToEntityGroup`	将实体添加到组中。
`removeEntitiesFromEntityGroup`	从组中移除实体。

实体数据查询工具（19）

跨所有实体类型的复杂筛选查询。支持实体字段、属性以及带键筛选的最新遥测数据。

工具	描述
`findEntityDataBySingleEntityFilter`	按 ID 查找单个实体的数据。
`findEntityDataByEntityGroupFilter` (PE)	按实体组查找数据。
`findEntityDataByEntityListFilter`	查找实体 ID 列表的数据。
`findEntityDataByEntityNameFilter`	按名称前缀查找数据。
`findEntityDataByEntityTypeFilter`	按实体类型查找数据。
`findEntityDataByEntityGroupListFilter` (PE)	查找多个组的数据。
`findEntityDataByEntityGroupNameFilter` (PE)	按名称前缀查找组的数据。
`findEntityDataByEntitiesGroupNameFilter` (PE)	查找指定名称组内实体的数据。
`findEntityDataByStateEntityOwnerFilter`	查找实体所有者的数据。
`findEntityDataByAssetTypeFilter`	按类型查找资产。
`findEntityDataByDeviceTypeFilter`	按类型查找设备。
`findEntityDataByEdgeTypeFilter`	按类型查找边。
`findEntityDataByEntityViewTypeFilter`	按类型查找实体视图。
`findEntityDataByRelationsQueryFilter`	查找相关实体。
`findEntityDataByAssetSearchQueryFilter`	查找相关资产。
`findEntityDataByDeviceSearchQueryFilter`	查找相关设备。
`findEntityDataByEntityViewSearchQueryFilter`	查找相关实体视图。
`findEntityDataByApiUsageStateFilter`	查找 API 使用数据。
`findEntityDataByEdgeQueryFilter`	查找相关边。

实体计数查询工具（18）

统计符合筛选条件的实体。筛选类型与实体数据查询相同。

工具	描述
`countBySingleEntityFilter`	按单个实体 ID 计数。
`countByEntityGroupFilter` (PE)	按实体组计数。
`countByEntityListFilter`	按实体 ID 列表计数。
`countByEntityNameFilter`	按名称前缀计数。
`countByEntityTypeFilter`	按实体类型计数。
`countByEntityGroupListFilter` (PE)	按多个组计数。
`countByEntityGroupNameFilter` (PE)	按组名称前缀计数。
`countByEntitiesGroupNameFilter` (PE)	统计指定名称组中的实体数量。
`countByAssetTypeFilter`	按类型统计资产数量。
`countByDeviceTypeFilter`	按类型统计设备数量。
`countByEdgeTypeFilter`	按类型统计边数量。
`countByEntityViewTypeFilter`	按类型统计实体视图数量。
`countByApiUsageStateFilter`	统计 API 使用记录行数。
`countByRelationsQueryFilter`	统计相关实体数量。
`countByAssetSearchQueryFilter`	统计相关资产数量。
`countByDeviceSearchQueryFilter`	统计相关设备数量。
`countByEntityViewSearchQueryFilter`	统计相关实体视图数量。
`countByEdgeQueryFilter`	统计相关边数量。

指南工具 (3)

帮助大模型构建正确查询的文档工具。

工具	描述
`getEdqGuide`	获取有关创建实体数据查询的文档。
`getEdqCountGuide`	获取有关创建实体计数查询的文档。
`getKeyFiltersGuide`	获取有关创建关键过滤器的文档。

许可证

本项目采用 Apache License 2.0 许可 — 详情请参阅 LICENSE 文件。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。