ThingsPanel MCP

Official
# ThingsPanel MCP [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) [![Python Version](https://img.shields.io/pypi/pyversions/thingspanel-mcp.svg)](https://pypi.org/project/thingspanel-mcp/) [![PyPI version](https://badge.fury.io/py/thingspanel-mcp.svg)](https://badge.fury.io/py/thingspanel-mcp) [ThingsPanel](http://thingspanel.io/) 物联网平台的MCP(Model Context Protocol)服务器。 [English](README.md) | [中文](README_CN.md) 这个MCP服务器将ThingsPanel物联网平台与支持模型上下文协议的AI模型(如Claude、GPT等)集成在一起。它为AI模型提供了一种标准化的方式来: - 查询ThingsPanel中的设备信息和状态 - 检索设备历史数据进行分析 - 管理设备(创建、更新、删除) - 访问产品目录和模板 - 监控并响应告警和通知 - 通过ThingsPanel向物联网设备发送命令 通过使用这个MCP服务器,AI助手可以以安全、受控的方式直接与您的物联网设备和数据交互,从而实现强大的应用场景,如自然语言设备控制、数据可视化请求、异常检测以及基于设备数据的智能自动化。 ## 适用人群 ### 目标用户 - **物联网解决方案开发者**:在ThingsPanel物联网平台上构建解决方案并希望集成AI能力的工程师和开发人员 - **AI集成专家**:寻求将AI模型与物联网系统连接的专业人士 - **系统管理员**:负责管理物联网基础设施并希望启用AI驱动的分析和控制的IT人员 - **产品团队**:构建结合物联网和AI功能的产品的团队 ### 解决的问题 - **集成复杂性**:消除了在AI模型和物联网平台之间构建自定义集成的需求 - **标准化访问**:为AI模型提供与物联网数据和设备交互的一致接口 - **安全控制**:管理AI访问物联网系统的身份验证和授权 - **降低技术门槛**:降低为现有物联网部署添加AI能力的技术障碍 ### 理想应用场景 - **自然语言物联网控制**:使用户能够通过AI助手使用自然语言控制设备 - **智能数据分析**:允许AI模型访问和分析物联网传感器数据以获取洞察 - **异常检测**:将AI模型连接到设备数据流,实现实时异常检测 - **预测性维护**:通过提供设备历史访问,实现AI驱动的预测性维护 - **自动化报告**:创建能够根据请求生成物联网数据报告和可视化的系统 - **运营优化**:使用AI基于历史模式优化设备操作 ## 功能特点 - [x] 设备管理 - [x] 分页和筛选列出设备 - [x] 通过ID获取设备详情 - [x] 创建新设备 - [x] 更新现有设备 - [x] 删除设备 - [ ] 批量设备操作 - [ ] 设备分组 - [x] 数据检索和分析 - [x] 查询设备历史数据 - [x] 按时间范围筛选 - [x] 按特定属性筛选 - [x] 获取最新设备数据 - [ ] 设备数据统计分析 - [ ] 数据可视化端点 - [x] 产品管理 - [x] 分页列出产品 - [x] 获取产品详情 - [ ] 创建和更新产品 - [ ] 产品模板管理 - [x] 告警和通知 - [x] 列出设备告警 - [x] 按状态、严重性和时间筛选告警 - [ ] 创建和更新告警 - [ ] 确认和解决告警 - [ ] 配置告警规则 - [ ] 命令和控制 - [ ] 向设备发送命令 - [ ] 调度设备操作 - [ ] 批量命令操作 - [x] 集成 - [x] 模型上下文协议(MCP)支持 - [x] 传输选项(stdio, SSE) - [x] Docker容器支持 - [ ] Webhook支持 - [ ] 第三方API集成 工具列表是可配置的,允许您根据需求或上下文窗口限制启用或禁用特定功能。 ## 安装 ```bash pip install thingspanel-mcp ``` 或从源代码安装: ```bash git clone https://github.com/yourusername/thingspanel-mcp.git cd thingspanel-mcp pip install -e . ``` ## 配置 通过环境变量进行配置: - `THINGSPANEL_URL`:ThingsPanel API URL(默认值:http://thingspanel.io/) - `THINGSPANEL_API_KEY`:您的ThingsPanel API密钥 ### 设置API密钥 API密钥必须正确设置才能与ThingsPanel平台进行身份验证。ThingsPanel使用`x-api-key`请求头进行身份验证。 您可以通过以下几种方式设置API密钥: 1. **环境变量(推荐)**: ```bash export THINGSPANEL_API_KEY=您的API密钥 ``` 2. **与命令一起内联使用**: ```bash THINGSPANEL_API_KEY=您的API密钥 thingspanel-mcp ``` 3. **在.env文件中**: 在项目目录中创建一个`.env`文件: ``` THINGSPANEL_URL=http://thingspanel.io/ THINGSPANEL_API_KEY=您的API密钥 ``` 要验证您的API密钥是否正常工作,可以使用直接API调用进行测试: ```bash curl -H "x-api-key: 您的API密钥" http://thingspanel.io/api/v1/device/group/tree ``` ## 使用方法 启动MCP服务器: ```bash thingspanel-mcp ``` 这将使用默认的stdio传输方式启动服务器。您也可以使用SSE传输方式: ```bash thingspanel-mcp --transport sse ``` 查看所有可用选项: ```bash thingspanel-mcp --help ``` ## Docker使用方法 您也可以在Docker容器中运行ThingsPanel MCP: ### 使用Docker Compose(推荐) 1. 在环境中设置您的API密钥: ```bash export THINGSPANEL_API_KEY=your_api_key ``` 2. 启动服务: ```bash docker-compose up -d ``` 这将同时启动ThingsPanel MCP服务器和用于调试的MCP Inspector。 ### 直接使用Docker 1. 构建Docker镜像: ```bash docker build -t thingspanel-mcp . ``` 2. 运行容器: ```bash docker run -p 8000:8000 -e THINGSPANEL_API_KEY=your_api_key thingspanel-mcp ``` ## 手动测试 您可以使用MCP Inspector对MCP服务器进行手动测试。这将帮助您了解服务器的功能以及它如何响应不同的请求。 ### 测试准备 首先,确保您的API密钥已设置在环境中: ```bash export THINGSPANEL_API_KEY="您的API密钥" ``` 然后启动MCP检查器。您有两种选择: 1. 使用内置的inspect命令(推荐): ```bash thingspanel-mcp inspect ``` 2. 直接使用npx: ```bash npx @modelcontextprotocol/inspector ``` 启动Inspector后,在浏览器中访问 http://localhost:5173。 #### 列出设备 ```json { "limit": 10, "offset": 0 } ``` #### 获取设备详情 ```json { "device_id": "您的设备ID" } ``` #### 创建设备 ```json { "device_data": { "deviceNumber": "test-device-001", "deviceName": "测试设备001", "protocolType": "MQTT", "productId": "您的产品ID", "description": "这是一个测试设备" } } ``` 预期响应: ```json { "code": 200, "data": { "id": "新创建的设备ID", "deviceNumber": "test-device-001", "deviceName": "测试设备001", // ... 其他设备详情 } } ``` #### 更新设备 ```json { "device_id": "您的设备ID", "device_data": { "deviceName": "更新后的设备名称", "description": "更新后的设备描述" } } ``` 预期响应: ```json { "code": 200, "msg": "success" } ``` #### 删除设备 ```json { "device_id": "您的设备ID" } ``` 预期响应: ```json { "code": 200, "msg": "success" } ``` ### 参数格式 在MCP Inspector中使用工具时,请确保正确格式化参数: ✅ **正确的**参数格式: ```json { "limit": 10, "offset": 0 } ``` ❌ **错误的**格式(不要使用嵌套的"arguments"对象): ```json { "arguments": { "limit": 10, "offset": 0 } } ``` ### 测试示例 连接成功后,您可以测试各种可用工具。以下是一些示例: #### 列出设备 测试设备列表功能: 1. 选择 `list_devices` 工具 2. 输入参数: ```json { "limit": 10, "offset": 0 } ``` 3. 点击"Execute"(执行) 4. 您应该会看到来自ThingsPanel实例的设备列表响应 #### 获取设备详情 检索特定设备的信息: 1. 选择 `get_device` 工具 2. 输入参数(替换为实际设备ID): ```json { "device_id": "device123" } ``` 3. 点击"Execute"(执行) 4. 您应该会看到指定设备的详细信息 #### 查询设备数据 检索设备的历史数据: 1. 选择 `get_device_data` 工具 2. 输入参数(替换为实际设备ID): ```json { "device_id": "device123", "limit": 5, "attributes": ["temperature", "humidity"] } ``` 3. 点击"Execute"(执行) 4. 您应该会看到指定设备的历史数据点 #### 列出产品 检索产品信息: 1. 选择 `list_products` 工具 2. 输入参数: ```json { "limit": 5 } ``` 3. 点击"Execute"(执行) 4. 您应该会看到来自ThingsPanel的产品列表 #### 查看告警 检查设备告警: 1. 选择 `list_alarms` 工具 2. 输入参数: ```json { "limit": 5 } ``` 3. 点击"Execute"(执行) 4. 您应该会看到系统中的告警列表 ### 预期输出格式 所有响应都遵循标准格式: ```json { "code": 200, "data": { // 特定于每个工具的结果数据 }, "msg": "success" } ``` 错误响应将包含错误详情和非200的状态码。 ## 使用MCP Inspector进行调试 MCP Inspector是一个用于调试和测试MCP服务器的有用工具。使用方法: 1. 安装并运行MCP Inspector: ```bash npx @modelcontextprotocol/inspector ``` 2. 在浏览器中访问 http://localhost:5173 3. 在Inspector界面中配置连接: - 传输类型(Transport Type):STDIO - 命令(Command):thingspanel-mcp - 参数(Arguments):(留空或根据需要添加选项) 4. 点击"Connect"开始测试您的MCP服务器 或者,直接使用命令启动Inspector: ```bash npx @modelcontextprotocol/inspector -- thingspanel-mcp ``` ## 故障排除 ### 访问localhost:8000出现"Not Found" 如果在访问http://localhost:8000时看到"Not Found"错误,这是正常的。MCP服务器不是设计为通过网页浏览器直接访问的。它使用特定协议与AI模型通信。 ### MCP Inspector的端口冲突 如果遇到端口冲突错误,如`Error: listen EADDRINUSE: address already in use :::3000`: 1. 使用不同的端口: ```bash npx @modelcontextprotocol/inspector --port 3001 -- thingspanel-mcp ``` 2. 查找并终止使用3000端口的进程: ```bash lsof -i :3000 # 在macOS/Linux上 kill [PID] # 通过进程ID终止进程 ``` ### MCP Inspector中的连接错误 如果在尝试从Inspector连接到MCP服务器时遇到连接错误: 1. 确保您的ThingsPanel MCP服务器没有在另一个终端中运行 2. 检查命令和参数是否正确 3. 确保所有必需的环境变量都已设置 4. 尝试使用完整路径: ```bash npx @modelcontextprotocol/inspector -- $(which thingspanel-mcp) ``` ## 开发 1. 克隆仓库 2. 安装开发依赖:`pip install -e ".[dev,lint]"` 3. 运行测试:`pytest` ### 使用Makefile 项目包含一个Makefile,用于简化常见任务: ```bash make install # 安装开发依赖 make build # 构建包 make test # 运行测试 make run # 运行MCP服务器 make docker-build # 构建Docker镜像 make docker-run # 使用Docker Compose运行 make docker-stop # 停止Docker Compose服务 make clean # 清理构建产物 ``` ## 许可证 Apache License 2.0