ThingsBoard MCP Server

Table of Contents

• Overview
• Requirements
• Features
  • Entity Operations
  • Telemetry Management
  • Relations
  • Alarms
  • Entity Data Query
• Quick Start Guide
• Installation
  • Docker Image
  • Build from Sources
• Client Configuration
  • Binary Configuration
  • Docker Configuration
• Environment Variables
• Available Tools
  • Device Tools
  • Asset Tools
  • Customer Tools
  • User Tools
  • Alarm Tools
  • Entity Group Tools
  • Relation Tools
  • Telemetry Tools

Overview

The ThingsBoard MCP Server provides a natural language interface for LLMs and AI agents to interact with your ThingsBoard IoT platform.

You can ask questions such as Get my devices of type 'Air Quality Sensor' and receive structured results:

You can request to simulate or save time-series data in ThingsBoard:

Or, you can ask it to analyze your time-series data to find anomalies, spikes, or data gaps:

This server implements the Model Context Protocol (MCP), which enables AI systems to access and manipulate data in ThingsBoard through natural language commands. With this integration, you can:

• Query entities (device, asset, customer, etc.) data and telemetry using conversational language
• Manage entities through AI assistants
• Analyze IoT data and create reports using AI tools
• Automate ThingsBoard operations through AI-powered workflows

The server integrates seamlessly with MCP clients such as Claude Desktop, Cursor, and other AI applications that support the MCP protocol.

Requirements

Before you begin, ensure you have the following:

• ThingsBoard instance - A running ThingsBoard instance that the MCP server can connect to. You can use any of the following options:
  • Local/On-premise Community Edition: Self-hosted installation on your own infrastructure, or
  • Local/On-premise Professional Edition: Self-hosted installation on your own infrastructure, or
  • ThingsBoard Demo: Free shared instance at demo.thingsboard.io, or
  • ThingsBoard Cloud: Fully managed cloud service at thingsboard.cloud, or
  • EU ThingsBoard Cloud: Fully managed cloud service at eu.thingsboard.cloud, or
  • ThingsBoard Edge instance up and running
• Authentication credentials - Valid username and password with appropriate permissions on the ThingsBoard instance

Quick Start Guide

1. Configure your MCP client: Add the ThingsBoard MCP server to your client configuration (see Client Configuration)
2. Start using natural language: Begin interacting with your ThingsBoard instance through your MCP client

Features

Entity Operations

• Devices: Create, delete, view device details, credentials, and manage device relationships
• Assets: Create, delete, view, and manage asset relationships
• Customers: Create, delete, access customer information, titles, and manage customer relationships
• Users: Create, delete, manage users, tokens, activation links, and user assignments
• Entity Groups: Create, delete, view entity groups. Assign/unassign entities to specific group.

Telemetry Management

• Attribute Access: Retrieve attribute keys and values by scope for any entity
• Time-series Access: Get time-series data with various aggregation options
• Telemetry Insert/Update: Save attributes or time-series data with optional TTL settings

Relations

Create, delete, discover, and navigate relationships between entities with direction-based queries.

Alarms

Create, delete, fetch alarms, alarm types, and severity information for specific entities.

Entity Data Query

Run complex queries over platform entities (devices, assets, customers, etc.) and retrieve their data (fields, attributes, telemetry) in a structured, paginated format.

Installation

This MCP server works with ThingsBoard IoT Platform or ThingsBoard Edge. You'll need your ThingsBoard instance or Edge URL and valid credentials for the installation.

ThingsBoard Account

Before installing the MCP server, ensure you have:

1. Access to a ThingsBoard or Edge instance
2. A user account with sufficient permissions
3. The username and password for this account

Docker Image

The easiest way to get started is with the pre-built Docker image from Docker Hub.

Server Modes

The ThingsBoard MCP Server can run in two different modes:

• STDIO Mode (Standard Input/Output): The server communicates directly through standard input/output streams
• SSE Mode (Server-Sent Events): The server runs as an HTTP server that clients connect to

####…