thingsboard/thingsboard-mcp

98 stars 0 forks 质量 90 趋势 90

Connect AI agents to your ThingsBoard IoT platform via Model Context Protocol (MCP). Query devices, manage entities, analyze telemetry, and automate operations — all through natural language.

概览

Connect AI agents to your ThingsBoard IoT platform via Model Context Protocol (MCP). Query devices, manage entities, analyze telemetry, and automate operations — all through natural language.

README

ThingsBoard MCP Server

Connect AI agents to your ThingsBoard IoT platform via Model Context Protocol (MCP). Query devices, manage entities, analyze telemetry, and automate operations — all through natural language.

Works with Claude Desktop, Cursor, VS Code Copilot, Claude Code, and any MCP-compatible client.

Quick Start

You need a ThingsBoard instance (Cloud, EU Cloud, self-hosted CE/PE, or Edge) and an API key (ThingsBoard 4.3+) or username/password.

Legacy auth: If your ThingsBoard version is older than 4.3, use THINGSBOARD_USERNAME and THINGSBOARD_PASSWORD instead of THINGSBOARD_API_KEY.

What You Can Do

Ask questions in natural language and get structured results from your ThingsBoard instance:


Query devices and entities	Analyze time-series data

Generate and save telemetry	Get anomaly analysis

120+ tools across 10 tool groups:

Devices — create, update, delete, list, search by name/type/group
Assets — CRUD, list by tenant/customer, search
Customers — CRUD, list, search by title
Users — CRUD, list, admin/customer user management
Alarms — create, acknowledge, clear, delete, query by severity
Telemetry — read/write attributes and time-series, aggregation, TTL
Relations — create, delete, navigate entity relationships
OTA Packages — upload, download, assign firmware/software to devices
Entity Groups (PE) — manage groups, assign/remove entities
Entity Data Query — complex filtered queries across all entity types with attribute/telemetry filters

Installation

Docker (Recommended)

docker pull thingsboard/mcp

The Docker image supports two transport modes:

STDIO (default) — for clients that launch the server as a subprocess (Claude Desktop, Cursor, etc.)
SSE — for clients that connect over HTTP

See Quick Start for usage examples.

Download Binary

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

Run with:

# 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

Build from Source

Requires Java 17+ and 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

Configuration

Environment Variables

Variable	Description	Default
`THINGSBOARD_URL`	Base URL of your ThingsBoard instance	required
`THINGSBOARD_API_KEY`	API key for authentication (recommended for 4.3+)
`THINGSBOARD_USERNAME`	Username for authentication (legacy)
`THINGSBOARD_PASSWORD`	Password for authentication (legacy)
`THINGSBOARD_LOGIN_INTERVAL_SECONDS`	Session refresh interval	`1800`
`HTTP_BIND_ADDRESS`	HTTP bind address (SSE mode)	`127.0.0.1`
`HTTP_BIND_PORT`	HTTP port (SSE mode)	`8000`
`SPRING_AI_MCP_SERVER_STDIO`	Enable STDIO transport	`true`
`SPRING_WEB_APPLICATION_TYPE`	`none` for STDIO, `servlet` for SSE	`none`
`SPRING_AI_MCP_SERVER_SSE_ENDPOINT`	SSE endpoint path	`/sse`
`SPRING_AI_MCP_SERVER_SSE_MESSAGE_ENDPOINT`	SSE message endpoint path	`/mcp/message`

Tool Groups

The server exposes 120+ tools which may exceed context limits for some clients. Disable groups you don’t need:

Variable	Group	Tools	Default
`THINGSBOARD_TOOLS_EDQ`	Entity Data Query + Guides	40	`true`
`THINGSBOARD_TOOLS_TELEMETRY`	Telemetry & Attributes	11	`true`
`THINGSBOARD_TOOLS_DEVICE`	Devices	11	`true`
`THINGSBOARD_TOOLS_ASSET`	Assets	8	`true`
`THINGSBOARD_TOOLS_ALARM`	Alarms	9	`true`
`THINGSBOARD_TOOLS_OTA`	OTA Packages	11	`true`
`THINGSBOARD_TOOLS_RELATION`	Relations	8	`true`
`THINGSBOARD_TOOLS_CUSTOMER`	Customers	7	`true`
`THINGSBOARD_TOOLS_USER`	Users	9	`true`
`THINGSBOARD_TOOLS_GROUP`	Entity Groups (PE only)	10	`true`

Example — reduce to ~50 tools for clients with limited context:

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

Available Tools

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

View this README on GitHub

安装

docker run -i --rm -e THINGSBOARD_URL -e THINGSBOARD_API_KEY thingsboard/mcp

配置

{
  "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"
      }
    }
  }
}