ThingsBoard
- other
78
GitHub Stars
other
Language
6 months ago
First Indexed
2 months ago
Catalog Refreshed
Documentation & install
Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.
You will run the ThingsBoard MCP Server to enable natural language access to ThingsBoard data. This server lets AI agents and clients interact with devices, assets, customers, telemetry, alarms, and more through conversational commands, while returning structured results.
How to use
Start by configuring your MCP client to connect to the ThingsBoard MCP Server, then begin asking questions in natural language. You can query devices, assets, customers, users, and telemetry, manage entities and relationships, work with alarms, and perform complex data queries. The server translates natural language into actions against your ThingsBoard instance and returns structured results that you can act on.
How to install
Prerequisites: you need Docker installed on your machine.
Option A: Run the MCP server in STDIO mode using the official Docker image.
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
Option B: Run the MCP server in SSE mode with HTTP server access. Expose port 8000 and disable STDIO in the container configuration.
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
Additional installation notes
If you prefer to run the server from a release binary or build from sources, you can follow the separate flow provided for obtaining a runnable JAR and starting the server with Java. Use the appropriate command to start the server in STDIO or SSE mode after you obtain the artifact.
Environment variables
The server requires credentials to connect to your ThingsBoard instance. You provide URL, username, and password via environment variables.
Configuration overview
Two main server execution modes are supported: STDIO (standard input/output) and SSE (Server-Sent Events over HTTP). STDIO runs the server with a CLI-like container session, while SSE exposes an HTTP endpoint for clients to connect.
Notes on building and binaries
You can download a release binary or build from sources to run the server directly with Java. If you build, you will obtain a runnable JAR and can start the server with the appropriate Java command for STDIO or SSE mode.
Available tools
saveDevice
Create or update the device object.
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 credentials were not specified at creation, a random ACCESS_TOKEN is generated.
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.
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
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.
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
Returns a page of customers available for the user.
getCustomersByEntityGroupId
Returns a page of Customer objects that belongs to specified Entity Group Id.
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
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.
saveAlarm
Create or update the alarm object.
deleteAlarm
Delete the alarm by id.
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.
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.
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.
saveRelation
Create or update the relation object.
deleteRelation
Delete a relation between two entities.
deleteRelations
Delete all relations for the specified entity within the COMMON relation group.
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.
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).
findEntityDataBySingleEntityFilter
Find data for one entity by ID. Select fields, latest attributes/telemetry; optional key filters.
findEntityDataByEntityGroupFilter
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. Supports fields/latest values and optional key filters.
findEntityDataByEntityGroupListFilter
Find data for multiple groups of the same type using group IDs.
findEntityDataByEntityGroupNameFilter
Find data for groups by group type and group name starts-with.
findEntityDataByEntitiesGroupNameFilter
Find data for entities that belong to a group (by type + group name).
findEntityDataByStateEntityOwnerFilter
Find data for the owner of a specified entity.
findEntityDataByAssetTypeFilter
Find assets by type and name starts-with.
findEntityDataByDeviceTypeFilter
Find devices by type and name starts-with.
findEntityDataByEdgeTypeFilter
Find edges by type and name starts-with.
findEntityDataByEntityViewTypeFilter
Find entity views by type and name starts-with.
findEntityDataByRelationsQueryFilter
Find entities related to a root entity by relation query.
findEntityDataByAssetSearchQueryFilter
Find assets related to a root entity by relation type + allowed asset types.
findEntityDataByDeviceSearchQueryFilter
Find devices related to a root entity by relation type + allowed device types.
findEntityDataByEntityViewSearchQueryFilter
Find entity views related to a root entity by relation type + allowed view types.
findEntityDataByEdgeQueryFilter
Find edges related to a root entity by relation type + allowed edge types.
countBySingleEntityFilter
Count results for a single entity by ID with optional key filters.
countByEntityGroupFilter
Count results by Entity Group with optional key filters.
countByEntityListFilter
Count results for a list of entity IDs with optional key filters.
countByEntityNameFilter
Count results using name starts-with with optional key filters.
countByEntityTypeFilter
Count results by entity type with optional key filters.
countByEntityGroupListFilter
Count results for multiple groups using group IDs with optional key filters.
countByEntityGroupNameFilter
Count results for groups by group type and group name starts-with with optional key filters.
countByEntitiesGroupNameFilter
Count results for entities that belong to a group by type and group name with optional key filters.
countByStateEntityOwnerFilter
Count results for the owner of a specified entity 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.
