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.

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

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

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

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

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.

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

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

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

Tool Groups

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

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

Complex filtered queries across all entity types. Supports entity fields, attributes, and latest telemetry with key filters.

Count entities matching filters. Same filter types as Entity Data Query.

Documentation tools that help LLMs construct correct queries.

License

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