ThingsBoard MCP Server

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

Configure your MCP client: Add the ThingsBoard MCP server to your client configuration (see Client Configuration)
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:

Access to a ThingsBoard or Edge instance
A user account with sufficient permissions
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

Clone this repository
Build the project:

mvn clean install -DskipTests

The JAR file will be available in the target folder:

./target/thingsboard-mcp-server-1.0.0.jar

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.

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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

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,

Related MCP Servers

mcp2mqtt
mcp2everything
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
308
MIT License
ThingsPanel MCPofficial
ThingsPanel
-
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 -
37
Apache 2.0
Things MCP Server
wbopan
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
298
2
MIT License
ScreenMonitorMCP
inkbytefo
-
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 -
49
MIT License

View all related MCP servers