Overview

The ThingsBoard MCP (Model Context Protocol) Server provides a bridge between large language models (LLMs) or AI agents and a ThingsBoard IoT platform. It exposes high-level, structured “tools” that let an LLM query telemetry, read and write attributes, invoke device RPCs, inspect entities and alarms, and perform other common ThingsBoard operations using natural language or agent-driven workflows.

By translating natural-language requests into secure, auditable API calls against ThingsBoard, the MCP server makes it practical to embed IoT control and observability into conversational agents, automation pipelines, or orchestration agents. This enables use cases such as conversational device troubleshooting, automated dashboard generation, telemetry summarization, and agent-based alarm triage without embedding low-level ThingsBoard logic inside the LLM prompt.

Features

Exposes Tools for LLMs/agents to interact with ThingsBoard:
- Telemetry / time-series queries
- Server- and client-side attributes
- Device RPC invocation and command execution
- Entity discovery (devices, assets, customers, dashboards)
- Alarms and alarm management
LLM-agnostic: usable with any LLM or agent orchestration framework
Secure: connects to a ThingsBoard instance over configured credentials and supports environment-based secrets
Extensible: add new tools or adapt mappings to custom ThingsBoard models
Logging and audit-friendly responses designed for downstream agent reasoning

Installation / Configuration

Quick start options: run via Docker or build locally. Replace placeholders with your ThingsBoard instance URL and credentials.

Clone repository:

git clone https://github.com/thingsboard/thingsboard-mcp.git
cd thingsboard-mcp

Run with Docker:

docker build -t thingsboard-mcp:latest .
docker run -d \
  -e THINGSBOARD_URL="https://thingsboard.example.com" \
  -e THINGSBOARD_USERNAME="[email protected]" \
  -e THINGSBOARD_PASSWORD="your_password" \
  -p 8080:8080 \
  --name thingsboard-mcp \
  thingsboard-mcp:latest

Or run with Docker Compose (example):

version: '3.8'
services:
  mcp:
    image: thingsboard-mcp:latest
    environment:
      - THINGSBOARD_URL=https://thingsboard.example.com
      - [email protected]
      - THINGSBOARD_PASSWORD=your_password
    ports:
      - "8080:8080"

Configuration file (application.yml) example:

server:
  port: 8080

thingsboard:
  url: "https://thingsboard.example.com"
  username: "[email protected]"
  password: "your_password"
  apiTimeoutSeconds: 30

mcp:
  allowedOrigins: ["*"]
  logging:
    level: INFO

Important environment variables and config options:

Variable / Key	Purpose
THINGSBOARD_URL	Base URL for your ThingsBoard instance (HTTP(S))
THINGSBOARD_USERNAME	Login user for ThingsBoard API access
THINGSBOARD_PASSWORD	Password or API token for the user
MCP server port	Port where MCP listens (default 8080)
apiTimeoutSeconds	Timeout for calls to ThingsBoard

Tip: Use ThingsBoard API tokens or dedicated service accounts to limit privileges for the MCP integration.

Available Tools / Resources

The MCP server typically exposes a set of high-level tools to be consumed by LLMs or agents. Common resources include:

Telemetry Tool: query time-series data, aggregate, and summarize trends
Attributes Tool: read/write shared, server, and client attributes
RPC Tool: call device RPCs and handle responses
Entities Tool: search/list devices, assets, customers, dashboards
Alarms Tool: list, acknowledge, or clear alarms
Dashboards Tool: locate and reference dashboards for visualization links

The server usually provides a REST API and an OpenAPI/Swagger specification (check the repository for the exact endpoints) so agent frameworks can discover and invoke tools programmatically.

Use Cases

Conversational Device Troubleshooting
- User: “Why is device thermostat-21 reporting high temperature?”
- Flow: LLM asks MCP for recent telemetry trend and latest attributes; MCP queries ThingsBoard time-series and attributes, returns summarized trend and suspicious values.
Automated Alarm Triage
- Agent: periodically query open alarms for a site, summarize severity counts, and acknowledge non-critical alarms via the Alarms Tool.
Remote Command Execution
- Scenario: push a firmware update or toggle a digital output.
- Flow: LLM/agent composes a natural-language command → MCP maps it to a device RPC call and returns execution result.
Dashboard / Report Generation
- Use the Entities and Telemetry tools to collect metrics and auto-generate a link to a relevant ThingsBoard dashboard or create a sharable summary for stakeholders.
Data-driven Agent Workflows
- An AI agent monitors telemetry for anomalies; on detection, it uses MCP to gather context (attributes, recent events) and then initiates remediation (RPC or notifying a user).

Next Steps

Review the repository README and OpenAPI spec on GitHub: https://github.com/thingsboard/thingsboard-mcp
Configure a restricted ThingsBoard service account and test with a single device before enabling agent access in production
Integrate MCP with your preferred agent framework (LangChain, custom agent, or an LLM orchestration layer) and start by exposing one or two tools (e.g., Telemetry and RPC) to validate workflows

ThingsBoard MCP Server: Natural Language IoT Interface