ThingsPanel MCP

ThingsPanel MCP

ThingsPanel MCP 可将兼容 MCP 的助手连接到 ThingsPanel 和 ThingsVis API。它既提供专用的 IoT 工具，也提供名称独立、路由固定且经过源码审计的 API 工具。

English | 中文

包含内容

• 378 个 MCP 工具：364 个生成的 API 工具，以及 14 个专用设备、遥测、仪表盘和控制工具。
• 生成的工具集涵盖 ThingsPanel 的 312 个 API 操作和 ThingsVis 的 52 个 API 操作，包括设备、遥测、告警、分组、产品、服务访问、仪表盘和上传。
• 178 个生成的读取操作。其余 186 个写入或控制操作需要工具参数 confirmed=true。
• 结构化 JSON 结果、业务代码错误检测、路径编码、文件上传支持，以及有界的 SSE/WebSocket 读取。
• ThingsPanel 和 ThingsVis 的身份验证配置文件。连接的服务始终会强制执行授权。

完整的允许列表 API 清单位于 src/thingspanel_mcp/api_manifest.json。工具定义固定了 HTTP 方法和路由；调用方需提供 path_params、query、body 和可选的 file_path 值。

14 个专用工具会返回带有 ok、summary、data 和 error 字段的类型化 MCP structuredContent。程序化决策请使用 data 字段；summary 面向用户。send_device_command 在可用时会返回 message_id；将其传给 get_device_command_status，即可查询命令回执。命令已被接受并不代表设备已执行。

要求和安装

• Python 3.8 或更高版本。
• ThingsPanel 账户，以及目标 API 接受的凭据。ThingsVis 操作也可能需要 ThingsVis 凭据。

从 PyPI 安装：

python -m pip install --upgrade thingspanel-mcp

使用 uv 运行，无需持久安装：

uvx --from thingspanel-mcp thingspanel-mcp --help

从源码安装：

git clone https://github.com/ThingsPanel/thingspanel-mcp.git
cd thingspanel-mcp
python -m pip install .

身份验证和权限

ThingsPanel Community 支持 SYS_ADMIN 和 TENANT_ADMIN。它没有租户子用户；租户用户账户是 Enterprise 版的功能。ThingsPanel API 密钥对应租户管理员权限。系统管理员必须使用 ThingsPanel 登录 JWT。

ThingsVis 凭据与 ThingsPanel 凭据相互独立。ThingsVis SSO 交换使用所选配置中的 ThingsPanel JWT；ThingsVis 会在服务器间验证该令牌，并根据已验证的身份确定角色。MCP 调用方不能提交角色或用户身份来提升访问权限。

为每个身份使用一个配置。工具未指定 profile 时使用默认配置。14 个专用便捷工具使用默认配置；生成的 API 工具接受显式的 profile 参数。

创建 ~/.thingspanel/config.json：

{
  "base_url": "https://thingspanel.example.com",
  "api_prefix": "/api/v1",
  "thingsvis_base_url": "https://thingsvis.example.com",
  "thingsvis_api_prefix": "/api/v1",
  "profiles": {
    "default": {
      "thingspanel_token": "<tenant-admin-jwt>",
      "thingsvis_token": "<thingsvis-jwt>",
      "thingsvis_open_api_key": "<dashboard-open-api-key>"
    },
    "tenant_admin": {
      "thingspanel_token": "<tenant-admin-jwt>"
    },
    "superadmin": {
      "thingspanel_token": "<sys-admin-jwt>"
    }
  }
}

请妥善保管此文件；在 macOS 或 Linux 上，使用 chmod 600 ~/.thingspanel/config.json 限制访问权限。切勿提交真实凭据。

环境变量可以覆盖默认配置和端点：

THINGSPANEL_CONFIG_PATH
THINGSPANEL_BASE_URL
THINGSPANEL_API_PREFIX
THINGSPANEL_TOKEN
THINGSPANEL_API_KEY
THINGSPANEL_REFRESH_TOKEN
THINGSVIS_BASE_URL
THINGSVIS_API_PREFIX
THINGSVIS_TOKEN
THINGSVIS_REFRESH_TOKEN
THINGSVIS_OPEN_API_KEY
THINGSVIS_INTERNAL_SECRET

命名配置的凭据使用 THINGSPANEL_PROFILE_TOKEN、THINGSPANEL_PROFILEAPI_KEY、THINGSPANEL_PROFILETHINGSPANEL_REFRESH_TOKEN、THINGSPANEL_PROFILETHINGSVIS_TOKEN 和 THINGSPANEL_PROFILE_THINGSVIS_REFRESH_TOKEN。例如，THINGSPANEL_PROFILE_SUPERADMIN_TOKEN。环境凭据会在进程启动时加载。

对于单个默认身份，也可以使用命令行：

thingspanel-mcp --token "<ThingsPanel login JWT>" --base-url "https://thingspanel.example.com"

仅在以租户管理员身份连接时使用 --api-key。命令行中的令牌和 API 密钥参数可能会被本地进程检查工具看到；建议使用受保护的配置文件或密钥管理器。

配置 MCP 客户端

默认传输方式为 stdio。使用 --transport sse 可启用 SSE。请勿将凭据放在客户端配置中；应让服务指向受保护的配置文件，或使用客户端的环境变量支持。

Codex

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.thingspanel]
command = "uvx"
args = ["--from", "thingspanel-mcp==0.1.11", "thingspanel-mcp"]

[mcp_servers.thingspanel.env]
THINGSPANEL_CONFIG_PATH = "/absolute/path/to/.thingspanel/config.json"

更改配置后，重启或刷新 Codex MCP 服务。

Claude Desktop

在 claude_desktop_config.json 中添加服务条目：

{
  "mcpServers": {
    "thingspanel": {
      "command": "uvx",
      "args": ["--from", "thingspanel-mcp==0.1.11", "thingspanel-mcp"],
      "env": {
        "THINGSPANEL_CONFIG_PATH": "/absolute/path/to/.thingspanel/config.json"
      }
    }
  }
}

WorkBuddy

对于本地 stdio 使用，请在 ~/.workbuddy/mcp.json 中添加服务条目：

{
  "mcpServers": {
    "thingspanel": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "thingspanel-mcp==0.1.11", "thingspanel-mcp"],
      "env": {
        "THINGSPANEL_CONFIG_PATH": "/absolute/path/to/.thingspanel/config.json"
      }
    }
  }
}

此本地配置与发布 WorkBuddy 市场连接器是分开的。提交到市场还需要连接器元数据、MCP 清单、图标，并经过审核。对于用户输入的凭据，请遵循 WorkBuddy 的令牌身份验证配置。对于标准 MCP 工具架构，Skill 并非必需，但它有助于在这个大型工具集中引导工具选择和安全工作流。请参阅 WorkBuddy 连接器指南。

调用工具

每个生成的工具都恰好对应一个列入许可清单的 API 操作。例如，设备详情工具使用 path_params 传入路由标识符：

path_params = {"id": "device-id"}
profile = "tenant_admin"

在 query 中提供查询参数，在 body 中提供 JSON 请求数据。文件上传工具接受 file_path，并可按需接受 upload_field。请选择拥有所请求数据的 profile；不要要求 MCP 服务冒充其他角色。

对于每个生成的写入或控制工具，请先说明预期操作，并在宿主应用中征得用户同意。然后使用 confirmed=true 调用工具。如果 confirmed 为 false，工具会返回 confirmation_required 和请求预览，而不会发送请求。此标志是额外的防护措施，不能替代用户批准或后端授权。

流式工具接受范围为 1 到 20 的 stream_messages，以及范围为 1 到 30 的 stream_seconds。默认值分别为 5 条消息和 5 秒。

结果与故障排除

成功调用会返回类似以下内容的结构化结果：

{"ok": true, "status": 200, "data": {...}}

调用失败时会返回 ok=false，并在可用时附带状态和错误信息。即使 HTTP 状态为 200，也会检查 ThingsPanel 业务代码。

• 配置错误中提到某个 profile，表示该 profile 缺失，或未配置该服务所需的凭据。
• 401 或 403 表示凭据无效，或该凭据对应的服务端角色无权访问此操作。
• 返回 confirmation_required 表示这是写入操作的预览。仅在操作获批后才设置 confirmed=true。
• missing_path_parameter 错误表示 path_params 中缺少必需的路由值。
• SSE 和 WebSocket 结果会有意限制范围；部分结果可能意味着已达到配置的时间或消息数限制。
• 对于 URL 或代理问题，请检查该环境的服务基础 URL 和 API 前缀。

安全说明

• 服务端绝不信任调用方提供的角色；以已连接的后端为准。
• API 工具基于已检入的清单列入许可范围。它们不接受任意方法或 URL 值。
• 186 个生成的写入和控制工具都要求 confirmed=true，且仍受后端权限限制。
• 请求错误处理不会打印令牌和 API 密钥。请妥善保护本地配置文件，并根据组织的政策轮换凭据。

开发

使用 python -m pytest 运行单元测试。使用 python -m build 构建发布文件，然后使用 python -m twine check dist/* 验证其元数据。使用 tools/build_api_manifest.py 重新生成已检入的 API 清单，并使用 tools/audit_apifox_source.py 检查源文档差异。

许可证

Apache License 2.0。请参阅 LICENSE。