thingsboard/thingsboard-mcp

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.
Claude Desktop
Add to your claude_desktop_config.json:
Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
VS Code Copilot
Add to your VS Code settings.json or .vscode/mcp.json:
Claude Code
SSE Mode (any HTTP-based MCP client)
Start the server:
Then point your MCP client to http://localhost:8000/sse.
> **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)
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
Run with:
Binary client configuration
If you're using the JAR file instead of Docker, use this in your claude_desktop_config.json:
Build from Source
Requires Java 17+ and Maven 3.6+.
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 |
Advanced: connection and logging
| Variable | Description | Default |
|----------|-------------|---------|
| THINGSBOARD_CONNECTION_MAX_RETRIES | Max connection retry attempts | 3 |
| THINGSBOARD_CONNECTION_RETRY_DELAY_SECONDS | Delay between retries | 5 |
| THINGSBOARD_CONNECTION_CONNECT_TIMEOUT_SECONDS | HTTP connect timeout | 10 |
| THINGSBOARD_CONNECTION_READ_TIMEOUT_SECONDS | HTTP read timeout | 60 |
| LOG_LEVEL_APP | Application log level | info |
| LOG_LEVEL_TOOLS | Tool execution log level | info |
| LOG_LEVEL_TOOL_RESPONSE | Tool response log level | info |
| LOGGING_PATTERN_CONSOLE | Logback console pattern | %d{yyyy-MM-dd HH:mm:ss} \| %-5level \| %logger{1} \| %msg%n |
| LOGGING_CONSOLE_TARGET | Log output target | System.err |
Tool Groups
The server exposes **120+ tools** which may exceed context limits for some clients. Disable groups you don't need: