- Requirements - Entity Operations - Telemetry Management - Relations - OTA Packages - Entity Data Query - Quick Start Guide - Installation - Docker Image - Build from Sources - Client Configuration - Binary Configuration - Docker Configuration - Environment Variables - Tool Groups Configuration - Available Tools - Device Tools - Asset Tools - Customer Tools - User Tools - Alarm Tools - OTA Tools
Add this skill
npx mdskills install thingsboard/thingsboard-mcpComprehensive IoT platform integration with 120+ tools for device management, telemetry, and data analysis
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:
The server integrates seamlessly with MCP clients such as Claude Desktop, Cursor, and other AI applications that support the MCP protocol.
Before you begin, ensure you have the following:
Create, delete, discover, and navigate relationships between entities with direction-based queries.
Create, delete, fetch alarms, alarm types, and severity information for specific entities.
Create, upload, list, download, and delete OTA packages for device firmware/software updates.
Run complex queries over platform entities (devices, assets, customers, etc.) and retrieve their data (fields, attributes, telemetry) in a structured, paginated format.
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.
Before installing the MCP server, ensure you have:
The easiest way to get started is with the pre-built Docker image from Docker Hub.
The ThingsBoard MCP Server can run in two different modes:
For STDIO Mode, you must include the -i flag to keep stdin open:
docker pull thingsboard/mcp
docker run --rm -i -e THINGSBOARD_URL= -e THINGSBOARD_API_KEY= thingsboard/mcp
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= -e THINGSBOARD_API_KEY= -e SPRING_AI_MCP_SERVER_STDIO=false -e SPRING_WEB_APPLICATION_TYPE=servlet thingsboard/mcp
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/v2.1.0/thingsboard-mcp-server-2.1.0.jar
You can also build the JAR file from sources and run the ThingsBoard MCP Server directly.
mvn clean install -DskipTests
./target/thingsboard-mcp-server-2.1.0.jar
# For STDIO Mode
java -jar ./target/thingsboard-mcp-server-2.1.0.jar
# For SSE Mode
java -Dspring.ai.mcp.server.stdio=false -Dspring.main.web-application-type=servlet -jar ./target/thingsboard-mcp-server-2.1.0.jar
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.
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_API_KEY",
"thingsboard/mcp"
],
"env": {
"THINGSBOARD_URL": "",
"THINGSBOARD_API_KEY": ""
}
}
}
}
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-2.1.0.jar"
],
"env": {
"THINGSBOARD_URL": "",
"THINGSBOARD_API_KEY": ""
}
}
}
}
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_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 | 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 (must not be empty) | %d{yyyy-MM-dd HH:mm:ss} | %-5level | %logger{1} | %msg%n |
LOGGING_CONSOLE_TARGET | Log output target (System.err or System.out) | System.err |
HTTP_BIND_PORT | HTTP server port number | 8000 |
Authentication: Since ThingsBoard 4.3, we recommend using API keys instead of username/password. Create an API key in ThingsBoard UI under your user profile.
These variables can be set either:
-e flagenv configuration block in your MCP client setupThe MCP server provides 120+ tools which may exceed context limits for some MCP clients (e.g., Claude Desktop). You can disable entire tool groups to reduce the tool count and context size.
| Variable | Description | Default | Tools |
|---|---|---|---|
THINGSBOARD_TOOLS_EDQ | Entity Data Query tools + Guide tools | true | 40 |
THINGSBOARD_TOOLS_TELEMETRY | Telemetry and attributes tools | true | 11 |
THINGSBOARD_TOOLS_DEVICE | Device management tools | true | 11 |
THINGSBOARD_TOOLS_ASSET | Asset management tools | true | 8 |
THINGSBOARD_TOOLS_ALARM | Alarm management tools | true | 9 |
THINGSBOARD_TOOLS_OTA | OTA package management tools | true | 11 |
THINGSBOARD_TOOLS_RELATION | Relation management tools | true | 8 |
THINGSBOARD_TOOLS_CUSTOMER | Customer management tools | true | 7 |
THINGSBOARD_TOOLS_USER | User management tools | true | 9 |
THINGSBOARD_TOOLS_GROUP | Entity Group tools (PE only) | true | 10 |
If you experience "Context size exceeds the limit" errors, disable some tool groups:
{
"mcpServers": {
"thingsboard": {
"command": "java",
"args": ["-jar", "/path/to/thingsboard-mcp-server-2.1.0.jar"],
"env": {
"THINGSBOARD_URL": "",
"THINGSBOARD_API_KEY": "",
"THINGSBOARD_TOOLS_EDQ": "false",
"THINGSBOARD_TOOLS_OTA": "false",
"THINGSBOARD_TOOLS_GROUP": "false",
"THINGSBOARD_TOOLS_USER": "false"
}
}
}
}
This configuration reduces the tool count from ~120 to ~50 tools, which should work with most MCP clients.
The ThingsBoard MCP Server provides a wide range of tools that can be used through natural language commands. These tools are organized by category.
| Tool | Description |
|---|---|
createOrUpsertDevice | Create or update a device by name. Primary tool for most device tasks. |
saveDevice | Create or update the device object from raw JSON. Advanced tool. |
deleteDevice | Delete the device by id. |
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 (PE) | 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 (PE) | Returns a page of device objects that belongs to specified Entity Group Id. |
| Tool | Description |
|---|---|
saveAsset | Create or update the asset object. |
deleteAsset | Delete the asset by id. |
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 (PE) | Returns a page of assets objects available for the current user. |
getAssetsByEntityGroupId (PE) | Returns a page of asset objects that belongs to specified Entity Group Id. |
| Tool | Description |
|---|---|
saveCustomer | Create or update the customer object. |
deleteCustomer | Delete the customer by id. |
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 (PE) | Returns a page of customers available for the user. |
getCustomersByEntityGroupId (PE) | Returns a page of Customer objects that belongs to specified Entity Group Id. |
| Tool | Description |
|---|---|
saveUser | Create or update the user object. |
deleteUser | Delete the user by id. |
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 (PE) | 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 (PE) | Returns a page of user objects that belongs to specified Entity Group Id. |
| Tool | Description |
|---|---|
saveAlarm | Create or update the alarm object. |
deleteAlarm | Delete the alarm by id. |
ackAlarm | Acknowledge the alarm. |
clearAlarm | Clear the alarm. |
getAlarmInfoById | Get the Alarm info object based on the provided alarm id (includes originator name). |
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. |
| Tool | Description |
|---|---|
saveOtaPackageInfo | Create or update OTA package info. |
saveOtaPackageData | Upload OTA package binary data from a file path on the MCP host. Provide checksum only if you already have an official hash. |
downloadOtaPackage | Download OTA package binary to a local file path on the MCP host. |
getOtaPackageInfoById | Get OTA package info by id. |
getOtaPackageById | Get OTA package by id. |
getOtaPackages | Get OTA packages (paged). |
getOtaPackagesByDeviceProfile | Get OTA packages by device profile and type (paged). |
assignOtaPackageToDevice | Assign or clear OTA package for a device. |
assignOtaPackageToDeviceProfile | Assign or clear OTA package for a device profile. |
countByDeviceProfileAndEmptyOtaPackage | Count devices in a profile without assigned OTA package. |
deleteOtaPackage | Delete OTA package by id. |
| Tool | Description |
|---|---|
saveEntityGroup | Create or update the entity group object. |
deleteEntityGroup | Delete the entity group by id. |
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. |
addEntitiesToEntityGroup | Add entities to an entity group. |
removeEntitiesFromEntityGroup | Remove entities from an entity group. |
| Tool | Description |
|---|---|
saveRelation | Create or update the relation object. |
deleteRelation | Delete a relation between two entities. |
deleteRelations | Delete all relations (both 'from' and 'to' directions) for the specified entity within the COMMON relation group. |
getRelation | Returns relation object between two specified entities if present. |
findInfoByFrom | Returns list of relation info objects for the specified entity by the 'from' direction (includes entity names). |
findByFromWithRelationType | Returns list of relation objects for the specified entity by the 'from' direction and relation type. |
findInfoByTo | Returns list of relation info objects for the specified entity by the 'to' direction (includes entity names). |
findByToWithRelationType | Returns list of relation objects for the specified entity by the 'to' direction and relation type. |
| 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. |
saveEntityAttributesV2 | Save entity attributes. |
saveEntityTelemetry | Save entity telemetry data. |
saveEntityTelemetryWithTTL | Save entity telemetry data with time-to-live (TTL). |
| Tool | Description |
|---|---|
getEdqGuide | Get documentation for creating Entity Data Queries. |
getEdqCountGuide | Get documentation for creating Entity Count Queries. |
getKeyFiltersGuide | Get documentation and JSON schema for creating key filters (predicates over attributes/telemetry). |
| Tool | Description |
|---|---|
findEntityDataBySingleEntityFilter | Find data for one entity by ID. Select entity fields, latest attributes/telemetry; optional key filters for expressions over fields/attributes/latest TS. |
findEntityDataByEntityGroupFilter (PE) | Find data for entities using an Entity Group filter (group type + id). Supports fields/latest values and optional key filters. |
findEntityDataByEntityListFilter | Find data for a list of entity IDs (same type). Supports fields/latest values and optional key filters. |
findEntityDataByEntityNameFilter | Find data by name starts-with filter (same type). Supports fields/latest values and optional key filters. |
findEntityDataByEntityTypeFilter | Find data by entity type (CUSTOMER, USER, DASHBOARD, ASSET, DEVICE, EDGE, ENTITY_VIEW, etc.). Supports fields/latest values and optional key filters. |
findEntityDataByEntityGroupListFilter (PE) | Find data for multiple groups of the same type using group IDs. Supports fields/latest values and optional key filters. |
findEntityDataByEntityGroupNameFilter (PE) | Find data for groups by group type and group name starts-with. Supports fields/latest values and optional key filters. |
findEntityDataByEntitiesGroupNameFilter (PE) | Find data for entities that belong to a group (by type + group name). Supports fields/latest values and optional key filters. |
findEntityDataByStateEntityOwnerFilter | Find data for the owner (Tenant/Customer) of a specified entity. Supports fields/latest values and optional key filters. |
findEntityDataByAssetTypeFilter | Find assets by type and name starts-with. Supports fields/latest values and optional key filters. |
findEntityDataByDeviceTypeFilter | Find devices by type and name starts-with. Supports fields/latest values and optional key filters. |
findEntityDataByEdgeTypeFilter | Find edges by type and name starts-with. Supports fields/latest values and optional key filters. |
findEntityDataByEntityViewTypeFilter | Find entity views by type and name starts-with. Supports fields/latest values and optional key filters. |
findEntityDataByRelationsQueryFilter | Find entities related to a root entity (by relation query). Supports fields/latest values and optional key filters. |
findEntityDataByAssetSearchQueryFilter | Find assets related to a root entity (by relation type + allowed asset types). Supports fields/latest values and optional key filters. |
findEntityDataByDeviceSearchQueryFilter | Find devices related to a root entity (by relation type + allowed device types). Supports fields/latest values and optional key filters. |
findEntityDataByEntityViewSearchQueryFilter | Find entity views related to a root entity (by relation type + allowed view types). Supports fields/latest values and optional key filters. |
findEntityDataByApiUsageStateFilter | Find API usage data (tenant or customer-scoped). Supports fields/latest values and optional key filters. |
findEntityDataByEdgeQueryFilter | Find edges related to a root entity (by relation type + allowed edge types). Supports fields/latest values and optional key filters. |
| Tool | Description |
|---|---|
countBySingleEntityFilter | Count results for a single entity by ID with optional key filters. |
countByEntityGroupFilter (PE) | Count results by Entity Group (group type + id) with optional key filters. |
countByEntityListFilter | Count results for a list of entity IDs (same type) with optional key filters. |
countByEntityNameFilter | Count results using name starts-with (same type) with optional key filters. |
countByEntityTypeFilter | Count results by entity type with optional key filters. |
countByEntityGroupListFilter (PE) | Count results for multiple groups (same type) using group IDs with optional key filters. |
countByEntityGroupNameFilter (PE) | Count results for groups by group type and group name starts-with with optional key filters. |
countByEntitiesGroupNameFilter (PE) | Count results for entities that belong to a group (by type + group name) with optional key filters. |
countByAssetTypeFilter | Count assets by type and name starts-with with optional key filters. |
countByDeviceTypeFilter | Count devices by type and name starts-with with optional key filters. |
countByEdgeTypeFilter | Count edges by type and name starts-with with optional key filters. |
countByEntityViewTypeFilter | Count entity views by type and name starts-with with optional key filters. |
countByApiUsageStateFilter | Count API usage rows (optionally scoped by customer) with optional key filters. |
countByRelationsQueryFilter | Count entities related to a root entity with optional key filters. |
countByAssetSearchQueryFilter | Count assets related to a root entity with optional key filters. |
countByDeviceSearchQueryFilter | Count devices related to a root entity with optional key filters. |
countByEntityViewSearchQueryFilter | Count entity views related to a root entity with optional key filters. |
countByEdgeQueryFilter | Count edges related to a root entity with optional key filters. |
Install via CLI
npx mdskills install thingsboard/thingsboard-mcpThingsBoard MCP Server is a free, open-source AI agent skill. - Requirements - Entity Operations - Telemetry Management - Relations - OTA Packages - Entity Data Query - Quick Start Guide - Installation - Docker Image - Build from Sources - Client Configuration - Binary Configuration - Docker Configuration - Environment Variables - Tool Groups Configuration - Available Tools - Device Tools - Asset Tools - Customer Tools - User Tools - Alarm Tools - OTA Tools
Install ThingsBoard MCP Server with a single command:
npx mdskills install thingsboard/thingsboard-mcpThis downloads the skill files into your project and your AI agent picks them up automatically.
ThingsBoard MCP Server works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.