热门搜索:

thingsboard/mcp

thingsboard

通过模型上下文协议(MCP)将AI代理连接到ThingsBoard IoT平台，支持自然语言查询设备、管理实体、分析遥测数据和自动化操作，兼容Claude Desktop、Cursor、VS Code Copilot等MCP客户端。

下载次数: 0状态：社区镜像维护者：thingsboard仓库类型：镜像最近更新：3 个月前

让 AI 帮你使用轩辕镜像？ · 展开查看说明

如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。

只需在 AI 对话中先发送下面这句话即可：

请先完整阅读并严格遵守以下文档中的全部规则与要求：

https://xuanyuan.cloud/agents.md

在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。

查看 agents.md 用法指南与完整示范。国内用户首推元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。若 AI 无法访问外链，可打开说明文档复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。

镜像标签列表与下载命令

ThingsBoard MCP服务器

通过模型上下文协议(MCP)将AI代理连接到ThingsBoard物联网平台。可通过自然语言查询设备、管理实体、分析遥测数据和自动化操作。

兼容Claude Desktop、Cursor、VS Code Copilot、Claude Code及任何MCP兼容客户端。

快速开始

您需要一个ThingsBoard实例（云平台、欧盟云平台、自托管CE/PE或边缘版）以及API密钥（ThingsBoard 4.3+）或用户名/密码。

Claude Desktop

添加到您的claude_desktop_config.json：

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": "您的API密钥"
      }
    }
  }
}

Cursor

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

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": "您的API密钥"
      }
    }
  }
}

VS Code Copilot

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

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": "您的API密钥"
        }
      }
    }
  }
}

Claude Code

bash
claude mcp add thingsboard \
  -e THINGSBOARD_URL=https://thingsboard.cloud \
  -e THINGSBOARD_API_KEY=您的API密钥 \
  -- docker run -i --rm -e THINGSBOARD_URL -e THINGSBOARD_API_KEY thingsboard/mcp

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

启动服务器：

bash
docker run --rm -p 8000:8000 \
  -e THINGSBOARD_URL=https://thingsboard.cloud \
  -e THINGSBOARD_API_KEY=您的API密钥 \
  -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实例获取结构化结果：


查询设备和实体	分析时序数据
!https://raw.githubusercontent.com/thingsboard/thingsboard-mcp/refs/heads/master/images/get_my_devices_example.png	!https://raw.githubusercontent.com/thingsboard/thingsboard-mcp/refs/heads/master/images/analyze_data_example.png
生成和保存遥测数据	获取异常分析
!https://raw.githubusercontent.com/thingsboard/thingsboard-mcp/refs/heads/master/images/generate_sample_data_example.png	!https://raw.githubusercontent.com/thingsboard/thingsboard-mcp/refs/heads/master/images/analyze_result_example.png

120+工具覆盖10个工具组：

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

安装

Docker（推荐）

bash
docker pull thingsboard/mcp

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

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

参见快速开始获取使用示例。

下载二进制文件

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

运行：

bash
# 标准输入输出模式
java -jar thingsboard-mcp-server-2.1.0.jar

# SSE模式
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中使用以下配置：

json
{
  "mcpServers": {
    "thingsboard": {
      "command": "java",
      "args": ["-jar", "/绝对路径/thingsboard-mcp-server-2.1.0.jar"],
      "env": {
        "THINGSBOARD_URL": "https://thingsboard.cloud",
        "THINGSBOARD_API_KEY": "您的API密钥"
      }
    }
  }
}

从源码构建

需要Java 17+和Maven 3.6+。

bash
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`	启用标准输入输出传输	`true`
`SPRING_WEB_APPLICATION_TYPE`	`none`用于标准输入输出模式，`servlet`用于SSE模式	`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`	实体组（仅专业版）	10	`true`

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

json
{
  "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` (专业版)	返回当前用户可用的设备分页列表。
`getDevicesByIds`	按ID获取多个设备。
`getDevicesByEntityGroupId` (专业版)	返回指定实体组中的设备分页列表。

资产工具（8个）

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

客户工具（7个）

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

用户工具（9个）

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

告警工具（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包（分页）。
`getO

镜像拉取方式

您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本，请访问标签列表页面。

轩辕镜像加速拉取命令点我查看更多 mcp 镜像标签

docker pull docker.xuanyuan.run/thingsboard/mcp:<标签>

使用方法：

DockerHub 原生拉取命令

docker pull thingsboard/mcp:<标签>

轩辕镜像配置手册

按平台快速找到配置文档

Docker

登录仓库拉取

登录认证 · 私有仓库

专属域名拉取

免登录 · 高速拉取

Linux

Docker 镜像配置

Windows / Mac

Docker Desktop 配置

MacOS OrbStack

OrbStack 容器

Docker Compose

Compose 项目配置

NAS

群晖

Synology 配置

飞牛

fnOS 镜像配置

绿联

绿联 NAS

威联通

QNAP 配置

极空间

极空间 NAS

企业仓库

其他仓库

ghcr · Quay · nvcr

Harbor 镜像源

Proxy Repository 对接

Portainer 镜像源

Registries 配置

Nexus 镜像源

Docker Proxy 缓存

开发工具

Dev Containers

VS Code 开发容器

Podman

Podman 配置指南

Singularity / Apptainer

HPC 科学计算容器

Kubernetes

K8s Containerd

Kubernetes · Containerd

K3s

轻量级集群

面板 / 网络

爱快路由

iKuai 镜像加速

宝塔面板

一键配置镜像源

AI

用 AI 使用轩辕镜像

agents.md · AI 对话 · 提示词

一键安装

一键安装 Docker

Linux Docker 一键安装

需要其他帮助？请查看我们的常见问题 Docker 镜像访问常见问题解答或提交工单

镜像拉取常见问题

功能

免费版与专业版区别

功能对比 · 版本选择

支持的镜像仓库

Docker Hub · GCR · GHCR

新手拉取配置

docker search 限制

专属域名 · Hub 搜索

不支持 push

仅支持 pull · 不支持

拉取速度原因

带宽 · 缓存 · 冷热镜像

错误码

402 与流量用尽

402 · 流量包 · 充值

401 认证失败

401 · docker login

manifest unknown

标签错误 · 镜像不存在

410 Gone 排查

410 · Docker 升级

429 限流

免费版 · 请求频率

其他报错

DNS 超时

DNS 解析 · 网络超时

TLS 证书失败

no matching manifest（架构）

账号

失败是否计费

manifest · blob · 计费

申请开发票（企业 / 个人）

企业 · 个人 · 工单

修改登录密码

网站 · 仓库 · 重置

注销账户

工单 · 数据 · 注销

原理

mirrors 不生效

daemon.json · 重启

去掉域名前缀

docker tag · 重命名

指定架构拉取

ARM64 · AMD64 · 多架构

latest 与「最新」

digest · 版本号 · 标签

查看全部问题→

用户好评

来自真实用户的反馈，见证轩辕镜像的优质服务

oldzhang

运维工程师

Linux服务器

"Docker访问体验非常流畅，大镜像也能快速完成下载。"