{"id":30252084,"url":"https://github.com/thingsboard/thingsboard-mcp","last_synced_at":"2025-08-15T11:10:36.970Z","repository":{"id":308689976,"uuid":"1011333830","full_name":"thingsboard/thingsboard-mcp","owner":"thingsboard","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-14T15:56:57.000Z","size":953,"stargazers_count":61,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-14T17:36:43.064Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thingsboard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-30T16:48:34.000Z","updated_at":"2025-08-14T16:28:52.000Z","dependencies_parsed_at":"2025-08-07T10:41:59.377Z","dependency_job_id":null,"html_url":"https://github.com/thingsboard/thingsboard-mcp","commit_stats":null,"previous_names":["thingsboard/thingsboard-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thingsboard/thingsboard-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thingsboard%2Fthingsboard-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thingsboard%2Fthingsboard-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thingsboard%2Fthingsboard-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thingsboard%2Fthingsboard-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thingsboard","download_url":"https://codeload.github.com/thingsboard/thingsboard-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thingsboard%2Fthingsboard-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270558920,"owners_count":24606615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-15T11:10:34.476Z","updated_at":"2025-08-15T11:10:36.952Z","avatar_url":"https://github.com/thingsboard.png","language":"Java","readme":"# ThingsBoard MCP Server\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/thingsboard/mcp-server/blob/master/README.md) [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/thingsboard/thingsboard-mcp)](https://archestra.ai/mcp-catalog/thingsboard__thingsboard-mcp)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Requirements](#requirements)\n- [Features](#features)\n  - [Entity Operations](#entity-operations)\n  - [Telemetry Management](#telemetry-management)\n  - [Relations](#relations)\n  - [Alarms](#alarms)\n  - [Administration](#administration)\n- [Quick Start Guide](#quick-start-guide)\n- [Installation](#installation)\n  - [Docker Image](#docker-image)\n  - [Build from Sources](#build-from-sources)\n- [Client Configuration](#client-configuration)\n  - [Binary Configuration](#binary-configuration)\n  - [Docker Configuration](#docker-configuration)\n- [Environment Variables](#environment-variables)\n- [Available Tools](#available-tools)\n  - [Device Tools](#device-tools)\n  - [Asset Tools](#asset-tools)\n  - [Customer Tools](#customer-tools)\n  - [User Tools](#user-tools)\n  - [Alarm Tools](#alarm-tools)\n  - [Entity Group Tools](#entity-group-tools)\n  - [Relation Tools](#relation-tools)\n  - [Telemetry Tools](#telemetry-tools)\n  - [Admin Tools](#admin-tools)\n\n## Overview\n\nThe ThingsBoard MCP Server provides a **natural language interface** for LLMs and AI agents to interact with your ThingsBoard IoT platform. \n\nYou can ask questions such as “Get my devices of type 'Air Quality Sensor'” and receive structured results:\n\n![Get My Devices Example](images/get_my_devices_example.png)\n\nYou can request to simulate or save time-series data in ThingsBoard:\n\n![Generate Sample Data Example](images/generate_sample_data_example.png)\n\n![Generated Data In ThingsBoard](images/generated_data_in_tb_example.png)\n\nOr, you can ask it to analyze your time-series data to find anomalies, spikes, or data gaps:\n\n![Analyze Data Example](images/analyze_data_example.png)\n\n![Analyze Data Result](images/analyze_result_example.png)\n\nThis server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro), which enables AI systems to access and manipulate data in ThingsBoard through natural language commands. With this integration, you can:\n\n- Query entities (device, asset, customer, etc.) data and telemetry using conversational language\n- Manage entities through AI assistants\n- Analyze IoT data and create reports using AI tools\n- Automate ThingsBoard operations through AI-powered workflows\n\nThe server integrates seamlessly with MCP clients such as Claude Desktop, Cursor, and other AI applications that support the MCP protocol.\n\n## Requirements\n\nBefore you begin, ensure you have the following:\n\n- **ThingsBoard instance** - A running ThingsBoard instance that the MCP server can connect to. You can use any of the following options:\n  - **Local/On-premise Community Edition**: Self-hosted installation on your own [infrastructure](https://thingsboard.io/docs/user-guide/install/installation-options/), or\n  - **Local/On-premise Professional Edition**: Self-hosted installation on your own [infrastructure](https://thingsboard.io/docs/user-guide/install/pe/installation-options/), or\n  - **ThingsBoard Demo**: Free shared instance at [demo.thingsboard.io](https://demo.thingsboard.io), or\n  - **ThingsBoard Cloud**: Fully managed cloud service at [thingsboard.cloud](https://thingsboard.cloud), or\n  - **EU ThingsBoard Cloud**: Fully managed cloud service at [eu.thingsboard.cloud](https://eu.thingsboard.cloud), or\n  - **ThingsBoard Edge instance** [up and running](https://thingsboard.io/docs/user-guide/install/edge/installation-options/)\n- **Authentication credentials** - Valid username and password with appropriate permissions on the ThingsBoard instance\n\n## Quick Start Guide\n\n1. **Configure your MCP client**: Add the ThingsBoard MCP server to your client configuration (see [Client Configuration](#client-configuration))\n2. **Start using natural language**: Begin interacting with your ThingsBoard instance through your MCP client\n\n## Features\n\n### Entity Operations\n\n- **Devices**: View device details, credentials, profiles, and manage device relationships\n- **Assets**: View and manage assets, asset profiles, and asset relationships\n- **Customers**: Access customer information, titles, and manage customer relationships\n- **Users**: Manage users, tokens, activation links, and user assignments\n\n### Telemetry Management\n\n- **Attribute Access**: Retrieve attribute keys and values by scope for any entity\n- **Time-series Access**: Get time-series data with various aggregation options\n- **Telemetry Insert/Update**: Save attributes or time-series data with optional TTL settings\n\n### Relations\n\nDiscover and navigate relationships between entities with direction-based queries.\n\n### Alarms\n\nFetch alarms, alarm types, and severity information for specific entities.\n\n### Administration\n\n- **System Settings**: Access and manage administration settings\n- **Security Settings**: View security policies and JWT configuration\n- **Version Control**: Manage repository and auto-commit settings\n- **System Information**: Check for updates and retrieve usage statistics\n\n## Installation\n\nThis 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.\n\n### ThingsBoard Account\n\nBefore installing the MCP server, ensure you have:\n1. Access to a ThingsBoard or Edge instance\n2. A user account with sufficient permissions\n3. The username and password for this account\n\n### Docker Image\n\nThe easiest way to get started is with the pre-built Docker image from Docker Hub.\n\n#### Server Modes\n\nThe ThingsBoard MCP Server can run in two different modes:\n\n- **STDIO Mode (Standard Input/Output)**: The server communicates directly through standard input/output streams\n- **SSE Mode (Server-Sent Events)**: The server runs as an HTTP server that clients connect to\n\n#### Running in STDIO Mode (Default)\n\nFor STDIO Mode, you must include the `-i` flag to keep stdin open:\n\n```bash\ndocker pull thingsboard/mcp\ndocker run --rm -i -e THINGSBOARD_URL=\u003cyour_thingsboard_url\u003e -e THINGSBOARD_USERNAME=\u003cyour_username\u003e -e THINGSBOARD_PASSWORD=\u003cyour_password\u003e thingsboard/mcp\n```\n\n#### Running in SSE Mode\n\nIn SSE Mode, you must expose port 8000 using the `-p` flag and explicitly override the default settings :\n\n```bash\ndocker pull thingsboard/mcp\ndocker run --rm -p 8000:8000 -e THINGSBOARD_URL=\u003cyour_thingsboard_url\u003e -e THINGSBOARD_USERNAME=\u003cyour_username\u003e -e THINGSBOARD_PASSWORD=\u003cyour_password\u003e -e SPRING_AI_MCP_SERVER_STDIO=false -e SPRING_WEB_APPLICATION_TYPE=servlet thingsboard/mcp\n```\n\n### Build from Sources\n\nYou can also build the JAR file from sources and run the ThingsBoard MCP Server directly.\n\n#### Prerequisites\n\n- Java 17 or later\n- Maven 3.6 or later\n\n#### Build Steps\n\n1. Clone this repository\n2. Build the project:\n\n```bash\nmvn clean install -DskipTests\n```\n\n3. The JAR file will be available in the target folder:\n\n```bash\n./target/thingsboard-mcp-server-1.0.0.jar\n```\n\n4. Run the server using the JAR file:\n\n```bash\n# For STDIO Mode\njava -jar ./target/thingsboard-mcp-server-1.0.0.jar\n```\n\n```bash\n# For SSE Mode\njava -Dspring.ai.mcp.server.stdio=false Dspring.main.web-application-type=servlet -jar ./target/thingsboard-mcp-server-1.0.0.jar\n```\n\n## Client Configuration\n\nTo 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.\n\n### Docker Configuration\n\nIf you're using the Docker image, use this configuration in your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"thingsboard\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\",\n        \"THINGSBOARD_URL\",\n        \"-e\",\n        \"THINGSBOARD_USERNAME\",\n        \"-e\",\n        \"THINGSBOARD_PASSWORD\",\n        \"-e\",\n        \"LOGGING_PATTERN_CONSOLE\",\n        \"thingsboard/mcp\"\n      ],\n      \"env\": {\n        \"THINGSBOARD_URL\": \"\u003cthingsboard_url\u003e\",\n        \"THINGSBOARD_USERNAME\": \"\u003cthingsboard_username\u003e\",\n        \"THINGSBOARD_PASSWORD\": \"\u003cthingsboard_password\u003e\",\n        \"LOGGING_PATTERN_CONSOLE\": \"\"\n      }\n    }\n  }\n}\n```\n\n### Binary Configuration\n\nIf you've built the JAR file from sources, use this configuration in your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"thingsboard\": {\n      \"command\": \"java\",\n      \"args\": [\n        \"-jar\",\n        \"/absolute/path/to/thingsboard-mcp-server-1.0.0.jar\"\n      ],\n      \"env\": {\n        \"THINGSBOARD_URL\": \"\u003cthingsboard_url\u003e\",\n        \"THINGSBOARD_USERNAME\": \"\u003cthingsboard_username\u003e\",\n        \"THINGSBOARD_PASSWORD\": \"\u003cthingsboard_password\u003e\",\n        \"LOGGING_PATTERN_CONSOLE\": \"\"\n      }\n    }\n  }\n}\n```\n\n## Environment Variables\n\nThe MCP server requires the following environment variables to connect to your ThingsBoard instance:\n\n| Variable | Description                                    | Default |\n|----------|------------------------------------------------|---------|\n| `THINGSBOARD_URL` | The base URL of your ThingsBoard instance      | |\n| `THINGSBOARD_USERNAME` | Username used to authenticate with ThingsBoard | |\n| `THINGSBOARD_PASSWORD` | Password used to authenticate with ThingsBoard | |\n| `THINGSBOARD_LOGIN_INTERVAL_SECONDS` | Login session refresh interval in seconds      | 1800 |\n| `SPRING_WEB_APPLICATION_TYPE` | Spring application type (none or servlet)     | none |\n| `SPRING_AI_MCP_SERVER_STDIO` | Enable/disable standard I/O communication      | true |\n| `SPRING_AI_MCP_SERVER_SSE_ENDPOINT` | Server-Sent Events (SSE) endpoint URL          | /sse |\n| `SPRING_AI_MCP_SERVER_SSE_MESSAGE_ENDPOINT` | Server-Sent Events message endpoint URL        | /mcp/message |\n| `SERVER_PORT` | HTTP server port number                        | 8080 |\n\nThese variables can be set either:\n- Directly via Docker command line using the `-e` flag\n- Or through the `env` configuration block in your MCP client setup\n\n## Available Tools\n\nThe ThingsBoard MCP Server provides a wide range of tools that can be used through natural language commands. These tools are organized by category.\n\n### Device Tools\n\n| Tool | Description |\n|------|-------------|\n| `getDeviceById` | Fetch the Device object based on the provided Device Id. |\n| `getDeviceCredentialsByDeviceId` | Get device credentials by device id. If during device creation there wasn't specified any credentials, platform generates random 'ACCESS_TOKEN' credentials. |\n| `getTenantDevices` | Returns a page of devices owned by tenant. |\n| `getTenantDevice` | Get tenant device by name. Device name is a unique property of device. |\n| `getCustomerDevices` | Returns a page of devices objects assigned to customer. |\n| `getUserDevices` | Returns a page of device objects available for the current user. |\n| `getDevicesByIds` | Get Devices By Ids. Requested devices must be owned by tenant or assigned to customer. |\n| `getDevicesByEntityGroupId` | Returns a page of device objects that belongs to specified Entity Group Id. |\n\n### Asset Tools\n\n| Tool | Description |\n|------|-------------|\n| `getAssetById` | Get the Asset object based on the provided Asset Id. |\n| `getTenantAssets` | Returns a page of assets owned by tenant. |\n| `getTenantAsset` | Get tenant asset by name. Asset name is a unique property of asset. |\n| `getCustomerAssets` | Returns a page of assets objects assigned to customer. |\n| `getUserAssets` | Returns a page of assets objects available for the current user. |\n| `getAssetsByIds` | Get Assets By Ids. Requested assets must be owned by tenant or assigned to customer. |\n| `getAssetsByEntityGroupId` | Returns a page of asset objects that belongs to specified Entity Group Id. |\n\n### Customer Tools\n\n| Tool | Description |\n|------|-------------|\n| `getCustomerById` | Get the Customer object based on the provided Customer Id. |\n| `getCustomers` | Returns a page of customers owned by tenant. |\n| `getTenantCustomer` | Get the Customer using Customer Title. |\n| `getUserCustomers` | Returns a page of customers available for the user. |\n| `getCustomersByEntityGroupId` | Returns a page of Customer objects that belongs to specified Entity Group Id. |\n\n### User Tools\n\n| Tool | Description |\n|------|-------------|\n| `getUserById` | Fetch the User object based on the provided User Id. |\n| `getUsers` | Returns a page of users owned by tenant or customer. |\n| `getTenantAdmins` | Returns a page of tenant administrator users assigned to the specified tenant. |\n| `getCustomerUsers` | Returns a page of users assigned to the specified customer. |\n| `getAllCustomerUsers` | Returns a page of users for the current tenant with authority 'CUSTOMER_USER'. |\n| `getUsersForAssign` | Returns page of user data objects that can be assigned to provided alarmId. |\n| `getUsersByEntityGroupId` | Returns a page of user objects that belongs to specified Entity Group Id. |\n\n### Alarm Tools\n\n| Tool | Description |\n|------|-------------|\n| `getAlarmById` | Get the Alarm object based on the provided alarm id. |\n| `getAlarmInfoById` | Get the Alarm info object based on the provided alarm id. |\n| `getAlarms` | Get a page of alarms for the selected entity. |\n| `getAllAlarms` | Get a page of alarms that belongs to the current user owner. |\n| `getHighestAlarmSeverity` | Get highest alarm severity by originator and optional status filters. |\n| `getAlarmTypes` | Get a set of unique alarm types based on alarms that are either owned by tenant or assigned to the customer. |\n\n### Entity Group Tools\n\n| Tool | Description |\n|------|-------------|\n| `getEntityGroupById` | Fetch the Entity Group object based on the provided Entity Group Id. |\n| `getEntityGroupsByType` | Fetch the list of Entity Group Info objects based on the provided Entity Type. |\n| `getEntityGroupByOwnerAndNameAndType` | Fetch the Entity Group object based on the provided owner, type and name. |\n| `getEntityGroupsByOwnerAndType` | Fetch the list of Entity Group Info objects based on the provided Owner Id and Entity Type. |\n| `getEntityGroupsForEntity` | Returns a list of groups that contain the specified Entity Id. |\n| `getEntityGroupsByIds` | Fetch the list of Entity Group Info objects based on the provided entity group ids list. |\n\n### Relation Tools\n\n| Tool | Description |\n|------|-------------|\n| `getRelation` | Returns relation object between two specified entities if present. |\n| `findByFrom` | Returns list of relation objects for the specified entity by the 'from' direction. |\n| `findInfoByFrom` | Returns list of relation info objects for the specified entity by the 'from' direction. |\n| `findByTo` | Returns list of relation objects for the specified entity by the 'to' direction. |\n| `findInfoByTo` | Returns list of relation info objects for the specified entity by the 'to' direction. |\n\n### Telemetry Tools\n\n| Tool | Description |\n|------|-------------|\n| `getAttributeKeys` | Get all attribute keys for the specified entity. |\n| `getAttributeKeysByScope` | Get all attribute keys for the specified entity and scope. |\n| `getAttributes` | Get attributes for the specified entity. |\n| `getAttributesByScope` | Get attributes for the specified entity and scope. |\n| `getTimeseriesKeys` | Get all time-series keys for the specified entity. |\n| `getLatestTimeseries` | Get the latest time-series values for the specified entity and keys. |\n| `getTimeseries` | Get time-series data for the specified entity, keys, and time range. |\n| `saveDeviceAttributes` | Save device attributes. |\n| `saveEntityAttributesV1` | Save entity attributes (version 1). |\n| `saveEntityAttributesV2` | Save entity attributes (version 2). |\n| `saveEntityTelemetry` | Save entity telemetry data. |\n| `saveEntityTelemetryWithTTL` | Save entity telemetry data with time-to-live (TTL). |\n\n### Admin Tools\n\n| Tool | Description |\n|------|-------------|\n| `getAdminSettings` | Get the Administration Settings object using specified string key. |\n| `getSecuritySettings` | Get the Security settings object that contains password policy, lockout limits, etc. |\n| `getSystemInfo` | Get main information about system. |\n| `getUsageInfo` | Retrieves usage statistics for the current tenant. |\n","funding_links":[],"categories":["Embedded \u0026 IoT","Data Access \u0026 Integration Mcp Servers","Other Tools and Integrations","Official Servers","📦 Other"],"sub_categories":["Version Control"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthingsboard%2Fthingsboard-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthingsboard%2Fthingsboard-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthingsboard%2Fthingsboard-mcp/lists"}