Thingsboard MCP

🚀 ThingsBoard MCP Server

The ThingsBoard MCP Server offers a natural language interface for LLMs and AI agents to interact with your ThingsBoard IoT platform, enabling seamless data access and manipulation through simple queries.

🚀 Quick Start

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 IoT Platform or ThingsBoard Edge. You'll need your ThingsBoard instance or Edge URL and valid credentials for the installation.

ThingsBoard Account

Before installing the MCP server, ensure you have:

1. Access to a ThingsBoard or Edge instance.
2. A user account with sufficient permissions.
3. 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:

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:

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

1. Clone this repository.
2. Build the project:

mvn clean install -DskipTests

3. The JAR file will be available in the target folder:

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

4. Run the server using the JAR file:

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

# 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:

{
  "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:

{
  "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

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.