Skip to main content
Glama

ThingsBoard MCP Server

Official
by thingsboard

ThingsBoard MCP Server

License Trust Score

Table of Contents

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:

Get My Devices Example

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

Generate Sample Data Example

Generated Data In ThingsBoard

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

Analyze Data Example

Analyze Data Result

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:

  • 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: 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 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

Running in STDIO Mode (Default)

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

docker pull thingsboard/mcp docker run --rm -i -e THINGSBOARD_URL=<your_thingsboard_url> -e THINGSBOARD_USERNAME=<your_username> -e THINGSBOARD_PASSWORD=<your_password> thingsboard/mcp

Running in SSE Mode

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

docker pull thingsboard/mcp docker run --rm -p 8000:8000 -e THINGSBOARD_URL=<your_thingsboard_url> -e THINGSBOARD_USERNAME=<your_username> -e THINGSBOARD_PASSWORD=<your_password> -e SPRING_AI_MCP_SERVER_STDIO=false -e SPRING_WEB_APPLICATION_TYPE=servlet thingsboard/mcp

Download release binary

Alternatively, you can download the release binary (JAR file) and use it with the LLM Agent. Run the following command to download the binary to your PC:

wget https://github.com/thingsboard/thingsboard-mcp/releases/download/v1.0.0/thingsboard-mcp-server-1.0.0.jar

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 this repository

  2. Build the project:

mvn clean install -DskipTests
  1. The JAR file will be available in the target folder:

./target/thingsboard-mcp-server-1.0.0.jar
  1. Run the server using the JAR file:

# For STDIO Mode java -jar ./target/thingsboard-mcp-server-1.0.0.jar
# For SSE Mode java -Dspring.ai.mcp.server.stdio=false Dspring.main.web-application-type=servlet -jar ./target/thingsboard-mcp-server-1.0.0.jar

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.

Docker Configuration

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

{ "mcpServers": { "thingsboard": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "THINGSBOARD_URL", "-e", "THINGSBOARD_USERNAME", "-e", "THINGSBOARD_PASSWORD", "-e", "LOGGING_PATTERN_CONSOLE", "thingsboard/mcp" ], "env": { "THINGSBOARD_URL": "<thingsboard_url>", "THINGSBOARD_USERNAME": "<thingsboard_username>", "THINGSBOARD_PASSWORD": "<thingsboard_password>", "LOGGING_PATTERN_CONSOLE": "" } } } }

Binary Configuration

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

{ "mcpServers": { "thingsboard": { "command": "java", "args": [ "-jar", "/absolute/path/to/thingsboard-mcp-server-1.0.0.jar" ], "env": { "THINGSBOARD_URL": "<thingsboard_url>", "THINGSBOARD_USERNAME": "<thingsboard_username>", "THINGSBOARD_PASSWORD": "<thingsboard_password>", "LOGGING_PATTERN_CONSOLE": "" } } } }

Environment Variables

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

Variable

Description

Default

THINGSBOARD_URL

The base URL of your ThingsBoard instance

THINGSBOARD_USERNAME

Username used to authenticate with ThingsBoard

THINGSBOARD_PASSWORD

Password used to authenticate with ThingsBoard

THINGSBOARD_LOGIN_INTERVAL_SECONDS

Login session refresh interval in seconds

1800

SPRING_WEB_APPLICATION_TYPE

Spring application type (none or servlet)

none

SPRING_AI_MCP_SERVER_STDIO

Enable/disable standard I/O communication

true

SPRING_AI_MCP_SERVER_SSE_ENDPOINT

Server-Sent Events (SSE) endpoint URL

/sse

SPRING_AI_MCP_SERVER_SSE_MESSAGE_ENDPOINT

Server-Sent Events message endpoint URL

/mcp/message

LOGGING_PATTERN_CONSOLE

Logback console log pattern

SERVER_PORT

HTTP server port number

8080

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

Tool

Description

getDeviceById

Fetch the Device object based on the provided Device Id.

getDeviceCredentialsByDeviceId

Get device credentials by device id. If during device creation there wasn't specified any credentials, platform generates random 'ACCESS_TOKEN' credentials.

getTenantDevices

Returns a page of devices owned by tenant.

getTenantDevice

Get tenant device by name. Device name is a unique property of device.

getCustomerDevices

Returns a page of devices objects assigned to customer.

getUserDevices

Returns a page of device objects available for the current user.

getDevicesByIds

Get Devices By Ids. Requested devices must be owned by tenant or assigned to customer.

getDevicesByEntityGroupId

Returns a page of device objects that belongs to specified Entity Group Id.

Asset Tools

Tool

Description

getAssetById

Get the Asset object based on the provided Asset Id.

getTenantAssets

Returns a page of assets owned by tenant.

getTenantAsset

Get tenant asset by name. Asset name is a unique property of asset.

getCustomerAssets

Returns a page of assets objects assigned to customer.

getUserAssets

Returns a page of assets objects available for the current user.

getAssetsByIds

Get Assets By Ids. Requested assets must be owned by tenant or assigned to customer.

getAssetsByEntityGroupId

Returns a page of asset objects that belongs to specified Entity Group Id.

Customer Tools

Tool

Description

getCustomerById

Get the Customer object based on the provided Customer Id.

getCustomers

Returns a page of customers owned by tenant.

getTenantCustomer

Get the Customer using Customer Title.

getUserCustomers

Returns a page of customers available for the user.

getCustomersByEntityGroupId

Returns a page of Customer objects that belongs to specified Entity Group Id.

User Tools

Tool

Description

getUserById

Fetch the User object based on the provided User Id.

getUsers

Returns a page of users owned by tenant or customer.

getTenantAdmins

Returns a page of tenant administrator users assigned to the specified tenant.

getCustomerUsers

Returns a page of users assigned to the specified customer.

getAllCustomerUsers

Returns a page of users for the current tenant with authority 'CUSTOMER_USER'.

getUsersForAssign

Returns page of user data objects that can be assigned to provided alarmId.

getUsersByEntityGroupId

Returns a page of user objects that belongs to specified Entity Group Id.

Alarm Tools

Tool

Description

getAlarmById

Get the Alarm object based on the provided alarm id.

getAlarmInfoById

Get the Alarm info object based on the provided alarm id.

getAlarms

Get a page of alarms for the selected entity.

getAllAlarms

Get a page of alarms that belongs to the current user owner.

getHighestAlarmSeverity

Get highest alarm severity by originator and optional status filters.

getAlarmTypes

Get a set of unique alarm types based on alarms that are either owned by tenant or assigned to the customer.

Entity Group Tools

Tool

Description

getEntityGroupById

Fetch the Entity Group object based on the provided Entity Group Id.

getEntityGroupsByType

Fetch the list of Entity Group Info objects based on the provided Entity Type.

getEntityGroupByOwnerAndNameAndType

Fetch the Entity Group object based on the provided owner, type and name.

getEntityGroupsByOwnerAndType

Fetch the list of Entity Group Info objects based on the provided Owner Id and Entity Type.

getEntityGroupsForEntity

Returns a list of groups that contain the specified Entity Id.

getEntityGroupsByIds

Fetch the list of Entity Group Info objects based on the provided entity group ids list.

Relation Tools

Tool

Description

getRelation

Returns relation object between two specified entities if present.

findByFrom

Returns list of relation objects for the specified entity by the 'from' direction.

findByFromWithRelationType

Returns list of relation objects for the specified entity by the 'from' direction and relation type.

findInfoByFrom

Returns list of relation info objects for the specified entity by the 'from' direction.

findByTo

Returns list of relation objects for the specified entity by the 'to' direction.

findByToWithRelationType

Returns list of relation objects for the specified entity by the 'to' direction and relation type.

findInfoByTo

Returns list of relation info objects for the specified entity by the 'to' direction.

Telemetry Tools

Tool

Description

getAttributeKeys

Get all attribute keys for the specified entity.

getAttributeKeysByScope

Get all attribute keys for the specified entity and scope.

getAttributes

Get attributes for the specified entity.

getAttributesByScope

Get attributes for the specified entity and scope.

getTimeseriesKeys

Get all time-series keys for the specified entity.

getLatestTimeseries

Get the latest time-series values for the specified entity and keys.

getTimeseries

Get time-series data for the specified entity, keys, and time range.

saveDeviceAttributes

Save device attributes.

saveEntityAttributesV1

Save entity attributes (version 1).

saveEntityAttributesV2

Save entity attributes (version 2).

saveEntityTelemetry

Save entity telemetry data.

saveEntityTelemetryWithTTL

Save entity telemetry data with time-to-live (TTL).

Admin Tools

Tool

Description

getAdminSettings

Get the Administration Settings object using specified string key.

getSecuritySettings

Get the Security settings object that contains password policy, lockout limits, etc.

getSystemInfo

Get main information about system.

getUsageInfo

Retrieves usage statistics for the current tenant.

-
security - not tested
A
license - permissive license
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Connect your AI workflows to the ThingsBoard IoT Platform through this MCP server. Enables LLMs to query device telemetry, manage IoT entities (devices, assets, customers), and analyze sensor data - all through natural language. Perfect for building AI-powered IoT monitoring, predictive maintenance,

  1. Table of Contents
    1. Overview
      1. Requirements
        1. Quick Start Guide
          1. Features
            1. Entity Operations
            2. Telemetry Management
            3. Relations
            4. Alarms
            5. Administration
          2. Installation
            1. ThingsBoard Account
            2. Docker Image
            3. Download release binary
            4. Build from Sources
          3. Client Configuration
            1. Docker Configuration
            2. Binary Configuration
          4. Environment Variables
            1. Available Tools
              1. Device Tools
              2. Asset Tools
              3. Customer Tools
              4. User Tools
              5. Alarm Tools
              6. Entity Group Tools
              7. Relation Tools
              8. Telemetry Tools
              9. Admin Tools

            Related MCP Servers

            • A
              security
              A
              license
              A
              quality
              Links IoT devices to AI large models using the MCP and MQTT protocols, enabling natural language control, real-time AI responses, and complex instruction execution for interconnected IoT devices.
              Last updated -
              3
              324
              MIT License
              • Apple
              • Linux
            • -
              security
              A
              license
              -
              quality
              An integration server that connects AI models with ThingsPanel IoT platform, allowing AI assistants to interact with IoT devices through natural language for device control, data retrieval, and management operations.
              Last updated -
              39
              Apache 2.0
              • Linux
              • Apple
            • A
              security
              A
              license
              A
              quality
              An MCP server that allows AI assistants like Claude Code, Claude Desktop, and Cursor to interact with Things.app on macOS, enabling task creation, updates, viewing, scheduling, and organization through natural language.
              Last updated -
              6
              23
              2
              MIT License
              • Apple
            • -
              security
              A
              license
              -
              quality
              An MCP server that provides AI with real-time screen monitoring capabilities and UI element intelligence, allowing AI to observe, analyze, and interact with screen content through features like smart clicking and text extraction.
              Last updated -
              53
              MIT License
              • Apple
              • Linux

            View all related MCP servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/thingsboard/thingsboard-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server