Name: Thingsboard
Author: thingsboard

ThingsBoard MCP Server

Connect AI agents to your ThingsBoard IoT platform via Model Context Protocol (MCP). Query devices, manage entities, analyze telemetry, and automate operations — all through natural language.

Works with Claude Desktop, Cursor, VS Code Copilot, Claude Code, and any MCP-compatible client.

Quick Start

You need a ThingsBoard instance (Cloud, EU Cloud, self-hosted CE/PE, or Edge) and an API key (ThingsBoard 4.3+) or username/password.

<details open> <summary>Claude Desktop</summary>

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "thingsboard": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "THINGSBOARD_URL", "-e", "THINGSBOARD_API_KEY", "thingsboard/mcp"],
      "env": {
        "THINGSBOARD_URL": "https://thingsboard.cloud",
        "THINGSBOARD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

</details> <details> <summary>Cursor</summary>

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "thingsboard": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "THINGSBOARD_URL", "-e", "THINGSBOARD_API_KEY", "thingsboard/mcp"],
      "env": {
        "THINGSBOARD_URL": "https://thingsboard.cloud",
        "THINGSBOARD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

</details> <details> <summary>VS Code Copilot</summary>

Add to your VS Code settings.json or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "thingsboard": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "-e", "THINGSBOARD_URL", "-e", "THINGSBOARD_API_KEY", "thingsboard/mcp"],
        "env": {
          "THINGSBOARD_URL": "https://thingsboard.cloud",
          "THINGSBOARD_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

</details> <details> <summary>Claude Code</summary>

claude mcp add thingsboard \
  -e THINGSBOARD_URL=https://thingsboard.cloud \
  -e THINGSBOARD_API_KEY=YOUR_API_KEY \
  -- docker run -i --rm -e THINGSBOARD_URL -e THINGSBOARD_API_KEY thingsboard/mcp

</details> <details> <summary>SSE Mode (any HTTP-based MCP client)</summary>

Start the server:

docker run --rm -p 8000:8000 \
  -e THINGSBOARD_URL=https://thingsboard.cloud \
  -e THINGSBOARD_API_KEY=YOUR_API_KEY \
  -e SPRING_AI_MCP_SERVER_STDIO=false \
  -e SPRING_WEB_APPLICATION_TYPE=servlet \
  thingsboard/mcp

Then point your MCP client to http://localhost:8000/sse.

</details>

Legacy auth: If your ThingsBoard version is older than 4.3, use THINGSBOARD_USERNAME and THINGSBOARD_PASSWORD instead of THINGSBOARD_API_KEY.

What You Can Do

Ask questions in natural language and get structured results from your ThingsBoard instance:


Query devices and entities	Analyze time-series data

Generate and save telemetry	Get anomaly analysis

120+ tools across 10 tool groups:

Devices — create, update, delete, list, search by name/type/group
Assets — CRUD, list by tenant/customer, search
Customers — CRUD, list, search by title
Users — CRUD, list, admin/customer user management
Alarms — create, acknowledge, clear, delete, query by severity
Telemetry — read/write attributes and time-series, aggregation, TTL
Relations — create, delete, navigate entity relationships
OTA Packages — upload, download, assign firmware/software to devices
Entity Groups (PE) — manage groups, assign/remove entities
Entity Data Query — complex filtered queries across all entity types with attribute/telemetry filters

Installation

Docker (Recommended)

docker pull thingsboard/mcp

The Docker image supports two transport modes:

STDIO (default) — for clients that launch the server as a subprocess (Claude Desktop, Cursor, etc.)
SSE — for clients that connect over HTTP

See Quick Start for usage examples.

Download Binary

wget https://github.com/thingsboard/mcp-server/releases/download/v2.1.0/thingsboard-mcp-server-2.1.0.jar

Run with:

# STDIO mode
java -jar thingsboard-mcp-server-2.1.0.jar

# SSE mode
java -Dspring.ai.mcp.server.stdio=false -Dspring.main.web-application-type=servlet -jar thingsboard-mcp-server-2.1.0.jar

<details> <summary>Binary client configuration</summary>

If you're using the JAR file instead of Docker, use this in your claude_desktop_config.json:

{
  "mcpServers": {
    "thingsboard": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/thingsboard-mcp-server-2.1.0.jar"],
      "env": {
        "THINGSBOARD_URL": "https://thingsboard.cloud",
        "THINGSBOARD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

</details>

Build from Source

Requires Java 17+ and Maven 3.6+.

git clone https://github.com/thingsboard/mcp-server.git
cd mcp-server
mvn clean install -DskipTests
java -jar target/thingsboard-mcp-server-2.1.0.jar

Configuration

Environment Variables

Variable	Description	Default
`THINGSBOARD_URL`	Base URL of your ThingsBoard instance	required
`THINGSBOARD_API_KEY`	API key for authentication (recommended for 4.3+)
`THINGSBOARD_USERNAME`	Username for authentication (legacy)
`THINGSBOARD_PASSWORD`	Password for authentication (legacy)
`THINGSBOARD_LOGIN_INTERVAL_SECONDS`	Session refresh interval	`1800`
`HTTP_BIND_ADDRESS`	HTTP bind address (SSE mode)	`127.0.0.1`
`HTTP_BIND_PORT`	HTTP port (SSE mode)	`8000`
`SPRING_AI_MCP_SERVER_STDIO`	Enable STDIO transport	`true`
`SPRING_WEB_APPLICATION_TYPE`	`none` for STDIO, `servlet` for SSE	`none`
`SPRING_AI_MCP_SERVER_SSE_ENDPOINT`	SSE endpoint path	`/sse`
`SPRING_AI_MCP_SERVER_SSE_MESSAGE_ENDPOINT`	SSE message endpoint path	`/mcp/message`

<details> <summary>Advanced: connection and logging</summary>

Variable	Description	Default
`THINGSBOARD_CONNECTION_MAX_RETRIES`	Max connection retry attempts	`3`
`THINGSBOARD_CONNECTION_RETRY_DELAY_SECONDS`	Delay between retries	`5`
`THINGSBOARD_CONNECTION_CONNECT_TIMEOUT_SECONDS`	HTTP connect timeout	`10`
`THINGSBOARD_CONNECTION_READ_TIMEOUT_SECONDS`	HTTP read timeout	`60`
`LOG_LEVEL_APP`	Application log level	`info`
`LOG_LEVEL_TOOLS`	Tool execution log level	`info`
`LOG_LEVEL_TOOL_RESPONSE`	Tool response log level	`info`
`LOGGING_PATTERN_CONSOLE`	Logback console pattern	`%d{yyyy-MM-dd HH:mm:ss} \| %-5level \| %logger{1} \| %msg%n`
`LOGGING_CONSOLE_TARGET`	Log output target	`System.err`

</details>

Tool Groups

The server exposes 120+ tools which may exceed context limits for some clients. Disable groups you don't need:

Variable	Group	Tools	Default
`THINGSBOARD_TOOLS_EDQ`	Entity Data Query + Guides	40	`true`
`THINGSBOARD_TOOLS_TELEMETRY`	Telemetry & Attributes	11	`true`
`THINGSBOARD_TOOLS_DEVICE`	Devices	11	`true`
`THINGSBOARD_TOOLS_ASSET`	Assets	8	`true`
`THINGSBOARD_TOOLS_ALARM`	Alarms	9	`true`
`THINGSBOARD_TOOLS_OTA`	OTA Packages	11	`true`
`THINGSBOARD_TOOLS_RELATION`	Relations	8	`true`
`THINGSBOARD_TOOLS_CUSTOMER`	Customers	7	`true`
`THINGSBOARD_TOOLS_USER`	Users	9	`true`
`THINGSBOARD_TOOLS_GROUP`	Entity Groups (PE only)	10	`true`

Example — reduce to ~50 tools for clients with limited context:

{
  "env": {
    "THINGSBOARD_TOOLS_EDQ": "false",
    "THINGSBOARD_TOOLS_OTA": "false",
    "THINGSBOARD_TOOLS_GROUP": "false",
    "THINGSBOARD_TOOLS_USER": "false"
  }
}

Available Tools

<details> <summary>Device Tools (11)</summary>

Tool	Description
`createOrUpsertDevice`	Create or update a device by name. Primary tool for most device tasks.
`saveDevice`	Create or update the device object from raw JSON. Advanced tool.
`deleteDevice`	Delete the device by id.
`getDeviceById`	Fetch the Device object based on the provided Device Id.
`getDeviceCredentialsByDeviceId`	Get device credentials by device id.
`getTenantDevices`	Returns a page of devices owned by tenant.
`getTenantDevice`	Get tenant device by name.
`getCustomerDevices`	Returns a page of devices assigned to customer.
`getUserDevices` (PE)	Returns a page of devices available for the current user.
`getDevicesByIds`	Get devices by ids.
`getDevicesByEntityGroupId` (PE)	Returns a page of devices in a specified entity group.

</details> <details> <summary>Asset Tools (8)</summary>

Tool	Description
`saveAsset`	Create or update the asset object.
`deleteAsset`	Delete the asset by id.
`getAssetById`	Get the Asset object by id.
`getTenantAssets`	Returns a page of assets owned by tenant.
`getTenantAsset`	Get tenant asset by name.
`getCustomerAssets`	Returns a page of assets assigned to customer.
`getUserAssets` (PE)	Returns a page of assets available for the current user.
`getAssetsByEntityGroupId` (PE)	Returns a page of assets in a specified entity group.

</details> <details> <summary>Customer Tools (7)</summary>

Tool	Description
`saveCustomer`	Create or update the customer object.
`deleteCustomer`	Delete the customer by id.
`getCustomerById`	Get the Customer object by id.
`getCustomers`	Returns a page of customers owned by tenant.
`getTenantCustomer`	Get customer by title.
`getUserCustomers` (PE)	Returns a page of customers available for the user.
`getCustomersByEntityGroupId` (PE)	Returns a page of customers in a specified entity group.

</details> <details> <summary>User Tools (9)</summary>

Tool	Description
`saveUser`	Create or update the user object.
`deleteUser`	Delete the user by id.
`getUserById`	Fetch the User object by id.
`getUsers`	Returns a page of users owned by tenant or customer.
`getTenantAdmins`	Returns a page of tenant administrator users.
`getCustomerUsers`	Returns a page of users assigned to a customer.
`getAllCustomerUsers` (PE)	Returns a page of all customer users for the current tenant.
`getUsersForAssign`	Returns users that can be assigned to an alarm.
`getUsersByEntityGroupId` (PE)	Returns a page of users in a specified entity group.

</details> <details> <summary>Alarm Tools (9)</summary>

Tool	Description
`saveAlarm`	Create or update the alarm object.
`deleteAlarm`	Delete the alarm by id.
`ackAlarm`	Acknowledge the alarm.
`clearAlarm`	Clear the alarm.
`getAlarmInfoById`	Get alarm info by id (includes originator name).
`getAlarms`	Get a page of alarms for th

…

Thingsboard

Installation

Configuration

How to use

README

ThingsBoard MCP Server

Quick Start

What You Can Do

Installation

Docker (Recommended)

Download Binary

Build from Source

Configuration

Environment Variables

Tool Groups

Available Tools

You might also like