# ThingsBoard MCP > ThingsBoard MCP Server lets your AI agent talk directly to your entire IoT ecosystem. You monitor device telemetry, check alarms by severity, and run commands (RPC) on hardware without opening the dashboard. It handles reading sensor data, saving attributes, and discovering assets across multiple scopes—all through simple natural language queries. ## Overview - **Category:** iot-hardware - **Price:** Free - **Tags:** iot-platform, device-management, telemetry, rpc-commands, smart-infrastructure ## Description Yo, listen up. This **ThingsBoard MCP Server** lets your AI client talk straight to your whole IoT setup. You don't gotta open that dashboard just to check something or flip a switch; you just ask your agent. If you need to find gear, start with finding it. Use the **`find_entities`** tool when you gotta locate specific assets, devices, or any entity across the entire platform using complex query filters. If you're keeping tabs on system alerts, use **`find_alarms`**. That lets you search for alarms by filtering on severity—like critical—or status, such as active. To check what your sensors are doing right now, use **`get_telemetry`**. It pulls the absolute latest sensor readings for any entity. If you're updating metadata—the non-time-series stuff like a device’s location or model number—you'll call **`save_attributes`**. Need to log data? Use **`save_telemetry`** to record a new time-series sensor reading, specifying the exact value and timestamp for an entity. If you wanna run commands on physical hardware, there are two tools. For commands that don't need confirmation—a straight fire-and-forget action—use **`send_oneway_rpc`**. But if the device needs to confirm the action was successful, use **`send_twoway_rpc`**. That sends the control command and waits for the physical hardware to send back a structured response. ## Tools ### find_alarms Searches for specific alarms by applying filters for severity and status (e.g., active, critical). ### find_entities Uses complex query filters to locate assets, devices, or other entities across the platform. ### get_telemetry Reads and returns the most recent sensor readings (telemetry values) for a specified entity. ### save_attributes Saves non-time-series data points or metadata (like location/model) to an entity's attributes. ### save_telemetry Logs a new time-series sensor reading, recording the specific value and timestamp for an entity. ### send_oneway_rpc Sends a command to a device that doesn't require a response or confirmation back to the server. ### send_twoway_rpc Sends a control command and waits for the physical device to send a structured response confirming the action. ## Prompt Examples **Prompt:** ``` Get the latest telemetry for device ID 'eb5672a0-1234-11ed'. ``` **Response:** ``` I've retrieved the telemetry for device eb5672a0-1234-11ed. The current temperature is 24.5°C and humidity is at 48%. ``` **Prompt:** ``` Send a two-way RPC command 'toggleSwitch' with params {'state': true} to device 'eb5672a0-1234-11ed'. ``` **Response:** ``` RPC command sent. The device responded with success: true. The switch state has been updated. ``` **Prompt:** ``` Find all active alarms with CRITICAL severity. ``` **Response:** ``` I found 2 critical alarms. One is a 'High Temperature' alarm on Thermostat-01 and the other is 'Connectivity Loss' on Gateway-Main. ``` ## Capabilities ### Check device sensor data The agent reads the latest telemetry values for any connected entity. ### Update device settings or metadata You save attributes and time-series data directly to specific entities across defined scopes. ### Run commands on hardware The agent sends both one-way (fire-and-forget) and two-way RPC calls to control physical devices. ### Find specific equipment You search the entire system using complex filters across all available entities, assets, or devices. ### Review active alerts The agent queries and filters alarms based on defined severity levels (e.g., CRITICAL) and status. ## Use Cases ### Investigating an unexpected temperature spike A facility manager notices a sensor reading is erratic. Instead of manually cross-referencing the device ID in the dashboard, they ask their agent: 'What was the telemetry for Thermostat-42 over the last hour?' The agent runs `get_telemetry`, retrieving the precise time-series data needed to pinpoint when and why the spike occurred. ### Performing a routine system diagnostic The DevOps team needs to confirm that all safety relays are operational. They tell their agent: 'Send a two-way RPC command to every relay in Sector B and ask for status.' The agent executes `send_twoway_rpc` across the group, gathering confirmation responses ('success: true') immediately. ### Auditing critical operational failures After a power outage, an SRE needs to know the full scope of damage. They ask: 'Show me all active alarms with CRITICAL severity.' The agent runs `find_alarms`, providing a filtered list that immediately guides repair crews to the worst-hit assets. ### Updating asset metadata after maintenance A field technician replaces a pump motor and updates its serial number. Instead of logging into the web portal, they tell their agent: 'Update the attributes for Pump 123 with the new SN: XYZ90.' The agent executes `save_attributes`, updating the asset record instantly. ## Benefits - Checks telemetry values without leaving chat. Instead of diving into the ThingsBoard dashboard to see if a sensor is working, you just ask for `get_telemetry`. The agent gives you the latest readings instantly. - Automates remote control logic using RPC calls. Need to cycle power or toggle a valve? You use `send_oneway_rpc` or `send_twoway_rpc`, and your agent handles the command execution and status check. - Pinpoints assets with precision. Instead of guessing which sensor is bad, you run `find_entities` with complex filters to locate every device in a specific zone or model type. - Streamlines incident response. You use `find_alarms` to pull up all CRITICAL alerts system-wide. This cuts down the time spent manually reviewing alarm logs by hours. - Maintains accurate records easily. Use `save_attributes` when a device gets updated (e.g., new firmware version) or `save_telemetry` to log a manual test reading, keeping your data clean. ## How It Works The bottom line is, you treat your entire industrial control system like a chat session—no dashboard clicking needed. 1. Subscribe to the ThingsBoard server and provide your specific Host URL and API Key. 2. Your AI client sends a natural language command, specifying the action (e.g., 'Find critical alarms'). 3. The MCP server executes the required tool call against the ThingsBoard API and returns structured data directly to your agent. ## Frequently Asked Questions **How do I find specific devices using the find_entities tool?** You use `find_entities` by providing complex filtering criteria, not just a name. You can search based on multiple parameters like 'status=active' AND 'location=warehouse'. This lets you narrow down your target group precisely. **Can I save sensor data with save_telemetry?** Yes, `save_telemetry` logs new time-series readings. You must provide the specific entity ID, the metric name (e.g., 'temperature'), and the value you want to record. **What's the difference between send_oneway_rpc and send_twoway_rpc?** The key difference is confirmation. `send_oneway_rpc` sends a command and forgets about it (fire-and-forget). `send_twoway_rpc`, however, requires the device to respond with structured data confirming if the action succeeded or failed. **Does find_alarms only show active alerts?** No. You can filter alarms by status and severity using `find_alarms`. This means you can specifically query for 'RESOLVED' alarms to audit past incidents, or 'ACTIVE' alarms with a CRITICAL severity. **How do I use get_telemetry to read the current state of a device?** It reads the absolute latest sensor values recorded for any given entity. You simply provide the entity ID, and the tool returns the most recent timestamped data points available. This is faster than querying historical logs when you just need 'what's it doing right now.' **When should I use save_attributes instead of logging sensor readings?** Use this tool to store static or semi-static metadata, not time-series data. Attributes cover details like firmware version, location coordinates, or owner name for an entity. Telemetry handles the fluctuating values (temperature, pressure) over time. **What credentials are required to initialize the ThingsBoard connection for any tool?** You must provide a valid ThingsBoard Host URL and an API Key during setup. These two pieces of information authenticate your agent with your specific instance, ensuring it can manage devices in your account space. Without them, no tool will work. **How do I use complex filters in find_entities to narrow down asset searches?** You pass structured filter criteria beyond a simple ID search. You can combine multiple conditions—for example, finding all assets that are 'Critical' AND have the tag 'Warehouse B.' This lets you drill down into specific groups of equipment. **Can I check the latest sensor readings for a specific device?** Yes. Use the `get_telemetry` tool by providing the entity type and ID. The agent will return the most recent time-series data points recorded for that device. **Is it possible to trigger a physical action on a device, like turning on a light?** Absolutely. You can use `send_oneway_rpc` for simple commands or `send_twoway_rpc` if you need to wait for a confirmation response from the device hardware. **How do I find all devices that currently have active critical alarms?** You can use the `find_alarms` tool with a query body specifying the severity as 'CRITICAL' and status as 'ACTIVE_UNACK' or 'ACTIVE_ACK'.