thingsboard-mcp-server

ThingsBoard MCP 服务

这是一个适用于 ThingsBoard 的 模型上下文协议（MCP） 服务。此项目允许 AI 助手（如 Claude Desktop）直接与您的 ThingsBoard 实例交互，以管理资产、设备、遥测数据、警报等。

这些工具由官方 Python SDK（tb-rest-client）自动生成，可确保 100% 的 API 覆盖率、严格的类型检查，以及直接从源代码提取的丰富文档。

🚀 功能

• 自动发现： 自动检测已安装的 ThingsBoard SDK 版本（CE 或 PE），并据此进行适配。
• 智能追踪： 将高级客户端方法（rest_client_ce.py）映射到其底层 API 控制器，以提取准确的文档字符串和签名。
• 严格验证： 包含一个测试套件（verify_tools.py），通过模拟 SDK 确保每个生成的工具都具有有效的输入、文档字符串和执行逻辑。
• 全面报告： 生成详细的 Markdown 文档（TOOLS_CE.md）和验证审计报告（VERIFICATION_REPORT_CE.md）。

---

📋 前置条件

• Python 3.10+
• ThingsBoard Python REST 客户端

pip install tb-rest-client

🛠️ 设置与生成

1. 生成工具 运行生成器脚本。该脚本会扫描已安装的 tb-rest-client 库，追踪方法调用，并生成 MCP 工具代码。

python3 generate_thingsboard_mcp.py

会发生什么？

• 创建 thingsboard_mcp/tools/ce/（如果已安装，还会创建 pe/）。
• 生成 TOOLS_CE.md 文件，列出所有可用工具及其说明和参数。
• 自动筛除内部实用方法和 lambda 函数。

2. 验证工具 运行验证套件，确保生成的代码有效且符合严格的质量标准。

python3 verify_final.py

会发生什么？

• 模拟 ThingsBoard SDK（无需真实连接）。
• 使用虚拟数据测试每个工具，确保其正确调用客户端。
• 生成 VERIFICATION_REPORT_CE.md，记录每个工具的通过/失败状态。

⚙️ 配置

服务需要以下环境变量才能连接到您的 ThingsBoard 实例。

变量	描述	默认值
TB_URL	您的 ThingsBoard URL	http://localhost:8080
TB_USERNAME	租户管理员用户名	[email protected]
TB_PASSWORD	租户管理员密码	tenant
TB_EDITION	要加载的版本（CE 或 PE）	PE

🏃‍♂️ 使用方法

选项 A：与 Claude Desktop 配合使用

将以下配置添加到您的 Claude Desktop 配置文件中： MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "thingsboard": {
      "command": "python3",
      "args": ["/absolute/path/to/thingsboard-mcp/thingsboard_mcp/main.py"],
      "env": {
        "TB_URL": "http://YOUR_TB_IP:8080",
        "TB_USERNAME": "[email protected]",
        "TB_PASSWORD": "your_password",
        "TB_EDITION": "CE"
      }
    }
  }
}

选项 B：手动运行（测试）

您可以直接在终端中运行服务，以测试连接或进行调试。

export TB_URL="http://localhost:8080"
export TB_USERNAME="[email protected]"
export TB_PASSWORD="tenant"
export TB_EDITION="CE"

python3 thingsboard_mcp/main.py

📂 项目结构。

├── generate_thingsboard_mcp.py # Scans SDK and generates tool code
├── verify_tools.py             # Mocks SDK and verifies generated tools
├── TOOLS_CE.md                 # Documentation of all generated tools
├── VERIFICATION_REPORT_CE.md   # Audit log of tool health
├── README.md                   # This file
└── thingsboard_mcp/            # The generated package
    ├── main.py                 # Entry point for MCP Server
    └── tools/
        ├── shared.py           # Shared utilities (Auth, JSON parsing)
        ├── ce/                 # Community Edition tools (Asset, Device, etc.)
        └── pe/                 # Professional Edition tools (if applicable)

🛡️ 故障排除

缺少工具？ 请检查 TOOLS_CE.md 或 generate_thingsboard_mcp.py 的控制台输出。以下情况会导致工具被跳过：

1. 它们对应内部线程方法（join、start）。
2. 源 SDK 中缺少该方法的文档字符串。
3. 该方法是 lambda 函数或偏函数。 连接错误？ 服务会在首次调用工具时立即尝试登录。请确保运行 MCP 服务的机器能够访问您的 TB_URL，且凭据正确。