ThingsBoard MCP Server

ThingsBoard MCP Server

Table of Contents

• Overview
• Requirements
• Features
  • Entity Operations
  • Telemetry Management
  • Relations
  • Alarms
  • Administration
• 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
  • Admin Tools

Overview

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

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 device data and telemetry using conversational language
• Manage assets, customers, and users 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 instance: Self-hosted ThingsBoard installation on your own infrastructure
  • ThingsBoard Community Edition: Free open-source version that can be installed locally
  • ThingsBoard Professional Edition: Self-hosted version with additional features
  • ThingsBoard Demo: Free shared instance available at demo.thingsboard.io (limited functionality)
  • ThingsBoard Cloud: Fully managed cloud service available at thingsboard.cloud (subscription-based)
• Authentication credentials - Valid username and password with appropriate permissions on the ThingsBoard instance
• Network connectivity - The MCP server must be able to reach the ThingsBoard instance via HTTP/HTTPS
• Environment configuration - Properly configured environment variables as specified in the Environment Variables section

Quick Start Guide

1. Choose your ThingsBoard instance: Use an existing instance or sign up for ThingsBoard Cloud
2. Get your credentials: Create or use an existing user account with appropriate permissions
3. Deploy the MCP server: Use one of the following methods:

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

Features

Entity Operations

• Devices: View device details, credentials, profiles, and manage device relationships
• Assets: View and manage assets, asset profiles, and asset relationships
• Customers: Access customer information, titles, and manage customer relationships
• Users: Manage users, tokens, activation links, and user assignments

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

Discover and navigate relationships between entities with direction-based queries.

Alarms

Fetch alarms, alarm types, and severity information for specific entities.

Administration

• System Settings: Access and manage administration settings
• Security Settings: View security policies and JWT configuration
• Version Control: Manage repository and auto-commit settings
• System Information: Check for updates and retrieve usage statistics

Installation

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

ThingsBoard Account

Before installing the MCP server, ensure you have:

1. Access to a ThingsBoard 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

Running in STDIO Mode (Default)

For STDIO Mode, you must include the -i flag to keep stdin open:

Running in SSE Mode

In SSE Mode, you must expose port 8000 using the -p flag and explicitly override the default settings :

Build from Sources

You can also build the JAR file from sources and run the ThingsBoard MCP Server directly.

Prerequisites

• Java 17 or later
• Maven 3.6 or later

Build Steps

1. Clone the repository
2. Build the project:

3. The JAR file will be available in the target folder:

4. Run the server using the JAR file:

Client Configuration

To launch the server as a container when your MCP client starts (e.g., Claude Desktop), you need to add the appropriate configuration to your client's settings.

Binary Configuration

If you've built the JAR file from sources, use this configuration in your claude_desktop_config.json:

Docker Configuration

If you're using the Docker image, use this configuration in your claude_desktop_config.json:

Environment Variables

The MCP server requires the following environment variables to connect to your ThingsBoard instance:

These variables can be set either:

• Directly via Docker command line using the -e flag
• Or through the env configuration block in your MCP client setup

Available Tools

The ThingsBoard MCP Server provides a wide range of tools that can be used through natural language commands. These tools are organized by category.

Device Tools

Asset Tools

Customer Tools

User Tools

Alarm Tools

Entity Group Tools

Relation Tools

Telemetry Tools

Admin Tools