Getting Started

The ThingsBoard MCP Server connects your MCP-compatible LLM client to a live ThingsBoard Edge node via the Model Context Protocol. It exposes a set of tools across multiple tool groups for querying, creating, and managing local edge data using natural language — no REST calls or dashboard clicks required.

The MCP server works with Claude Desktop, Cursor, VS Code Copilot, Claude Code, and any MCP-compatible client.

Prerequisites

Before you begin, ensure that you have:

A running ThingsBoard Edge instance, accessible over the network.
A Tenant Administrator username and password for the Edge instance.
An MCP-compatible LLM client, like Claude Desktop, Claude Code, Cursor, or VS Code with an MCP extension.

Setting up the MCP server

Docker image

Pull the Docker image:

docker pull thingsboard/mcp

Edit the Claude Desktop config file (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": "http://<edge_host>:8080",
        "THINGSBOARD_USERNAME": "<tenant_email>",
        "THINGSBOARD_PASSWORD": "<password>",
        "LOGGING_PATTERN_CONSOLE": ""
      }
    }
  }
}

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

{
  "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": "http://<edge_host>:8080",
        "THINGSBOARD_USERNAME": "<tenant_email>",
        "THINGSBOARD_PASSWORD": "<password>",
        "LOGGING_PATTERN_CONSOLE": ""
      }
    }
  }
}

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_USERNAME",
          "-e", "THINGSBOARD_PASSWORD",
          "-e", "LOGGING_PATTERN_CONSOLE",
          "thingsboard/mcp"
        ],
        "env": {
          "THINGSBOARD_URL": "http://<edge_host>:8080",
          "THINGSBOARD_USERNAME": "<tenant_email>",
          "THINGSBOARD_PASSWORD": "<password>",
          "LOGGING_PATTERN_CONSOLE": ""
        }
      }
    }
  }
}

Run the following command in your terminal:

claude mcp add thingsboard -e THINGSBOARD_URL=http://<edge_host>:8080 -e THINGSBOARD_USERNAME=<tenant_email> -e THINGSBOARD_PASSWORD=<password> -e "LOGGING_PATTERN_CONSOLE=" -- docker run -i --rm -e THINGSBOARD_URL -e THINGSBOARD_USERNAME -e THINGSBOARD_PASSWORD -e LOGGING_PATTERN_CONSOLE thingsboard/mcp

SSE (Server-Sent Events) transport is useful for HTTP-based clients or when running the server as a standalone service.

Start the server:

docker run --rm -p 8000:8000 -e THINGSBOARD_URL=http://<edge_host>:8080 -e THINGSBOARD_USERNAME=<tenant_email> -e THINGSBOARD_PASSWORD=<password> -e LOGGING_PATTERN_CONSOLE= -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.

When the client starts, thingsboard tools appear in the client’s tool panel.

Build from sources

As an alternative to Docker, you can build the JAR file and run the MCP server directly.

Prerequisites:

Java 17 or later
Maven 3.6 or later

To build the project:

Clone the thingsboard-mcp repository.
Build the project:
Terminal window
```
mvn clean install -DskipTests
```
The JAR file is available in the target folder:
```
./target/thingsboard-mcp-server-1.0.0.jar
```

Run the server:

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

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

Binary client configuration

To use the JAR with an MCP client instead of Docker, replace the command and args in your client config. Example for Claude Desktop:

{
  "mcpServers": {
    "thingsboard": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/thingsboard-mcp-server-1.0.0.jar"
      ],
      "env": {
        "THINGSBOARD_URL": "http://<edge_host>:8080",
        "THINGSBOARD_USERNAME": "<tenant_email>",
        "THINGSBOARD_PASSWORD": "<password>",
        "LOGGING_PATTERN_CONSOLE": ""
      }
    }
  }
}

The same pattern applies to Cursor, VS Code, and other MCP clients.