MCP Server

• Overview
• Requirements
• Quick Start Guide
• Features
  • Entity Operations
  • Telemetry Management
  • Relations
  • Alarms
  • Administration
• Installation
  • ThingsBoard Account
  • Docker Image
    • Server Modes
    • Running in STDIO Mode (Default)
    • Running in SSE Mode
  • Build from Sources
    • Prerequisites
    • Build Steps
• Client Configuration
  • Docker Configuration
  • Binary Configuration
• Environment Variables
• Available Tools
  • Device Tools
  • Asset Tools
  • Customer Tools
  • User Tools
  • Alarm Tools
  • Entity Group Tools
  • Relation Tools
  • Telemetry Tools
  • Admin Tools

Overview

The ThingsBoard MCP Server provides a natural language interface for LLMs and AI agents to interact with your ThingsBoard IoT platform.

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:

• Query entities (device, asset, customer, etc.) data and telemetry using conversational language
• Manage entities through AI assistants
• Analyze IoT data and create reports using AI tools
• Automate ThingsBoard operations through AI-powered workflows

The server integrates seamlessly with MCP clients such as Claude Desktop, Cursor, and other AI applications that support the MCP protocol.

Requirements

Before you begin, ensure you have the following:

• ThingsBoard Edge instance up and running

• Authentication credentials - Valid username and password with appropriate permissions on the ThingsBoard instance

Write down your ThingsBoard URL, username and password - we will use them as your_thingsboard_url, your_username and your_password in the next steps.

Quick Start Guide

1. Configure your MCP client: Add the ThingsBoard MCP server to your client configuration (see Client Configuration)
2. Start using natural language: Begin interacting with your ThingsBoard instance through your MCP client

Features

Entity Operations

• Devices: View device details, credentials, profiles, and manage device relationships
• Assets: View and manage assets, asset profiles, and asset relationships
• Customers: Access customer information, titles, and manage customer relationships
• Users: Manage users, tokens, activation links, and user assignments

Telemetry Management

• Attribute Access: Retrieve attribute keys and values by scope for any entity
• Time-series Access: Get time-series data with various aggregation options
• Telemetry Insert/Update: Save attributes or time-series data with optional TTL settings

Relations

Discover and navigate relationships between entities with direction-based queries.

Alarms

Fetch alarms, alarm types, and severity information for specific entities.

Administration

• System Settings: Access and manage administration settings
• Security Settings: View security policies and JWT configuration
• Version Control: Manage repository and auto-commit settings
• System Information: Check for updates and retrieve usage statistics

Installation

This MCP server works with ThingsBoard Edge. You’ll need your ThingsBoard Edge instance URL and valid credentials for the installation.

ThingsBoard Account

Before installing the MCP server, ensure you have:

• Access to a ThingsBoard Edge instance

• A user account with sufficient permissions
• The username and password for this account

Docker Image

The easiest way to get started is with the pre-built Docker image from Docker Hub.

Server Modes

The ThingsBoard MCP Server can run in two different modes:

• STDIO Mode (Standard Input/Output): The server communicates directly through standard input/output streams
• SSE Mode (Server-Sent Events): The server runs as an HTTP server that clients connect to

Running in STDIO Mode (Default)

For STDIO Mode, you must include the -i flag to keep stdin open:

1
2
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

Running in SSE Mode

In SSE Mode, you must expose port 8000 using the -p flag and explicitly override the default settings :

1
2
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

Build from Sources

You can also build the JAR file from sources and run the ThingsBoard MCP Server directly.

Prerequisites

• Java 17 or later
• Maven 3.6 or later

Build Steps

• Clone the repository
• Build the project:

1
mvn clean install -DskipTests

• The JAR file will be available in the target folder:

1
./target/thingsboard-mcp-server-1.0.0.jar

• Run the server using the JAR file:

1
2
# For STDIO Mode
java -jar ./target/thingsboard-mcp-server-1.0.0.jar

1
2
# For SSE Mode
java -Dspring.ai.mcp.server.stdio=false Dspring.main.web-application-type=servlet -jar ./target/thingsboard-mcp-server-1.0.0.jar

Client Configuration

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.

Docker Configuration

If you’re using the Docker image, use this configuration in your claude_desktop_config.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "mcpServers": {
    "thingsboard": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "THINGSBOARD_URL",
        "-e",
        "THINGSBOARD_USERNAME",
        "-e",
        "THINGSBOARD_PASSWORD",
        "-e",
        "LOGGING_PATTERN_CONSOLE",
        "thingsboard/mcp"
      ],
      "env": {
        "THINGSBOARD_URL": "<thingsboard_url>",
        "THINGSBOARD_USERNAME": "<thingsboard_username>",
        "THINGSBOARD_PASSWORD": "<thingsboard_password>",
        "LOGGING_PATTERN_CONSOLE": ""
      }
    }
  }
}

Binary Configuration

If you’ve built the JAR file from sources, use this configuration in your claude_desktop_config.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "mcpServers": {
    "thingsboard": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/thingsboard-mcp-server-1.0.0.jar"
      ],
      "env": {
        "THINGSBOARD_URL": "<thingsboard_url>",
        "THINGSBOARD_USERNAME": "<thingsboard_username>",
        "THINGSBOARD_PASSWORD": "<thingsboard_password>",
        "LOGGING_PATTERN_CONSOLE": ""
      }
    }
  }
}

Environment Variables

The MCP server requires the following environment variables to connect to your ThingsBoard instance:

These variables can be set either:

• Directly via Docker command line using the -e flag
• Or through the env configuration block in your MCP client setup

Available Tools

The ThingsBoard MCP Server provides a wide range of tools that can be used through natural language commands. These tools are organized by category.

Device Tools

Asset Tools

Customer Tools

User Tools

Alarm Tools

Entity Group Tools

Relation Tools

Telemetry Tools

Admin Tools