miot-mcp

Name	miot-mcp JSON
Version	1.0.3 JSON
	download
home_page	https://github.com/javen-yan/miot-mcp
Summary	Mijia smart device MCP server, providing device discovery, property read/write, action invoke and other functions
upload_time	2025-08-22 10:21:41
maintainer	None
docs_url	None
author	Javen Yan
requires_python	>=3.8
license	None
keywords	xiaomi mijia iot smart-home mcp automation
VCS
bugtrack_url
requirements	mcp mijiaAPI Pillow setuptools
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 米家智能设备 MCP 服务器

中文文档 | [English](README_EN.md)

基于 Model Context Protocol (MCP) 的米家智能设备控制服务器，提供设备发现、属性读写、动作调用、状态监控等功能。

## 功能特性

### 🔌 连接管理
- 支持用户名密码登录
- 支持二维码登录
- 自动保存和加载认证信息
- 连接状态监控

### 📱 设备管理
- 自动发现米家设备
- 设备搜索和过滤
- 获取设备属性和动作列表
- 批量操作支持

### 📊 状态监控
- 实时设备状态获取
- 设备状态缓存
- 批量状态刷新
- 状态变化追踪

### 🛠️ 系统功能
- 资源缓存管理
- 详细错误处理和日志
- 服务器状态监控
- 连通性测试

## 功能展示

### 🎯 核心功能
![功能特性](static/feature.png)

### 🔍 设备发现
![设备发现](static/discover-devices.png)

### 📱 设备信息
![设备信息](static/device-info.png)

### 🛠️ 工具列表
![工具列表](static/tools.png)

### 🖥️ 服务器状态
![服务器状态](static/server-info.png)

...

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置认证信息

设置环境变量：

```bash
export MIJIA_USERNAME="your_username"
export MIJIA_PASSWORD="your_password"
export MIJIA_ENABLE_QR="false"
export MIJIA_LOG_LEVEL="INFO"
```

### 3. 启动服务器

```bash
python mcp_server/mcp_server.py
```

### 4. 测试连接

```bash
python mcp_test.py
```

## AI 工具集成

### Claude Desktop 集成

在 Claude Desktop 配置文件中添加以下配置：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mijia": {
      "command": "python",
      "args": ["/path/to/miot-agent/mcp_server/mcp_server.py"],
      "env": {
        "MIJIA_USERNAME": "your_username",
        "MIJIA_PASSWORD": "your_password",
        "MIJIA_ENABLE_QR": "false",
        "MIJIA_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

### Continue.dev 集成

在 Continue 配置中添加：

```json
{
  "mcpServers": {
    "mijia": {
      "command": "python",
      "args": ["/path/to/miot-agent/mcp_server/mcp_server.py"],
      "env": {
        "MIJIA_USERNAME": "your_username",
        "MIJIA_PASSWORD": "your_password"
      }
    }
  }
}
```

### Cline 集成

对于 Cline（原 Claude Dev），添加 MCP 服务器配置：

```json
{
  "mcp": {
    "servers": {
      "mijia": {
        "command": "python",
        "args": ["/path/to/miot-agent/mcp_server/mcp_server.py"],
        "env": {
          "MIJIA_USERNAME": "your_username",
          "MIJIA_PASSWORD": "your_password"
        }
      }
    }
  }
}
```

### 通用 MCP 客户端集成

对于任何兼容 MCP 的客户端：

1. **命令**: `python /path/to/miot-agent/mcp_server/mcp_server.py`
2. **环境变量**:
   - `MIJIA_USERNAME`: 米家账户用户名
   - `MIJIA_PASSWORD`: 米家账户密码
   - `MIJIA_ENABLE_QR`: 设置为 "true" 启用二维码登录（可选）
   - `MIJIA_LOG_LEVEL`: 日志级别（DEBUG, INFO, WARNING, ERROR）

### 验证集成

集成完成后，您应该能在 AI 助手中看到以下工具：

- **连接管理**: `connect`, `connect_with_qr`, `disconnect`, `ping`
- **设备管理**: `discover_devices`, `search_devices`
- **属性操作**: `get_property_value`, `set_property_value`, `batch_set_properties`
- **动作操作**: `call_action`
- **状态监控**: `get_device_status`, `refresh_all_device_status`
- **家庭管理**: `get_homes`, `get_consumable_items`
- **场景管理**: `get_scenes_list`, `run_scene`
- **系统管理**: `get_server_status`, `clear_cache`

以及这些资源：
- `mijia://devices` - 设备列表
- `mijia://config` - 配置信息
- `mijia://device/{device_id}/properties` - 设备属性
- `mijia://device/{device_id}/actions` - 设备动作

## 工具使用指南

### 连接管理

#### 连接到米家云服务
```json
{
  "method": "tools/call",
  "params": {
    "name": "connect",
    "arguments": {}
  }
}
```

#### 断开连接
```json
{
  "method": "tools/call",
  "params": {
    "name": "disconnect",
    "arguments": {}
  }
}
```

### 设备发现和管理

#### 发现设备
```json
{
  "method": "tools/call",
  "params": {
    "name": "discover_devices",
    "arguments": {}
  }
}
```

#### 搜索设备
```json
{
  "method": "tools/call",
  "params": {
    "name": "search_devices",
    "arguments": {
      "name_filter": "台灯",
      "model_filter": "xiaomi",
      "online_only": true
    }
  }
}
```

### 设备属性操作

#### 获取设备属性列表
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_device_properties",
    "arguments": {
      "device_id": "123456789"
    }
  }
}
```

#### 获取属性值
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_property_value",
    "arguments": {
      "device_id": "123456789",
      "siid": 2,
      "piid": 1
    }
  }
}
```

#### 设置属性值
```json
{
  "method": "tools/call",
  "params": {
    "name": "set_property_value",
    "arguments": {
      "device_id": "123456789",
      "siid": 2,
      "piid": 1,
      "value": true
    }
  }
}
```

#### 批量设置属性
```json
{
  "method": "tools/call",
  "params": {
    "name": "batch_set_properties",
    "arguments": {
      "operations": [
        {
          "device_id": "123456789",
          "siid": 2,
          "piid": 1,
          "value": true
        },
        {
          "device_id": "987654321",
          "siid": 3,
          "piid": 2,
          "value": 50
        }
      ]
    }
  }
}
```

### 设备动作调用

#### 获取设备动作列表
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_device_actions",
    "arguments": {
      "device_id": "123456789"
    }
  }
}
```

#### 调用设备动作
```json
{
  "method": "tools/call",
  "params": {
    "name": "call_action",
    "arguments": {
      "device_id": "123456789",
      "siid": 2,
      "aiid": 1,
      "params": []
    }
  }
}
```

### 状态监控

#### 获取设备状态
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_device_status",
    "arguments": {
      "device_id": "123456789"
    }
  }
}
```

#### 刷新所有设备状态
```json
{
  "method": "tools/call",
  "params": {
    "name": "refresh_all_device_status",
    "arguments": {}
  }
}
```

#### 获取缓存状态
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_cached_device_status",
    "arguments": {
      "device_id": "123456789"
    }
  }
}
```

### 系统管理

#### 获取服务器状态
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_server_status",
    "arguments": {}
  }
}
```

#### 清除缓存
```json
{
  "method": "tools/call",
  "params": {
    "name": "clear_cache",
    "arguments": {}
  }
}
```

#### 测试连通性
```json
{
  "method": "tools/call",
  "params": {
    "name": "ping",
    "arguments": {
      "message": "hello"
    }
  }
}
```

### 家庭和场景管理

#### 获取家庭列表
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_homes",
    "arguments": {}
  }
}
```

#### 获取场景列表
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_scenes_list",
    "arguments": {
      "home_id": "123456789"
    }
  }
}
```

#### 执行场景
```json
{
  "method": "tools/call",
  "params": {
    "name": "run_scene",
    "arguments": {
      "scene_id": "987654321"
    }
  }
}
```

#### 获取耗材信息
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_consumable_items",
    "arguments": {
      "home_id": "123456789",
      "owner_id": 12345
    }
  }
}
```

## 资源访问

### 获取设备列表
```json
{
  "method": "resources/read",
  "params": {
    "uri": "mijia://devices"
  }
}
```

### 获取配置信息
```json
{
  "method": "resources/read",
  "params": {
    "uri": "mijia://config"
  }
}
```

### 获取设备属性
```json
{
  "method": "resources/read",
  "params": {
    "uri": "mijia://device/123456789/properties"
  }
}
```

### 获取设备动作
```json
{
  "method": "resources/read",
  "params": {
    "uri": "mijia://device/123456789/actions"
  }
}
```

## 错误处理

所有工具调用都会返回统一的错误格式：

```json
{
  "success": false,
  "error": "错误描述",
  "error_code": "ERROR_CODE",
  "timestamp": "2024-01-01T12:00:00Z"
}
```

常见错误代码：
- `ADAPTER_NOT_INITIALIZED`: 适配器未初始化
- `DEVICE_NOT_FOUND`: 设备未找到
- `PROPERTY_NOT_FOUND`: 属性未找到
- `ACTION_NOT_FOUND`: 动作未找到
- `CONNECTION_FAILED`: 连接失败
- `AUTHENTICATION_FAILED`: 认证失败

## 日志配置

日志级别可以通过环境变量设置：

```bash
# 环境变量
export MIJIA_LOG_LEVEL="DEBUG"
```

## 项目结构

```
miot-agent/
├── adapter/
│   ├── mijia_adapter.py      # 米家适配器实现
│   └── mijia_config.py       # 配置管理
├── mcp_server/
│   ├── mcp_server.py         # MCP服务器主程序
│   └── server_config.json    # 服务器配置
├── requirements.txt          # 项目依赖
├── mcp_test.py              # 测试脚本
└── README.md                # 项目文档
```

## 开发指南

### 添加新工具

1. 在 `mcp_server.py` 中添加工具函数：

```python
@mcp.tool()
async def your_new_tool(param1: str, param2: int = 0) -> str:
    """工具描述
    
    Args:
        param1: 参数1描述
        param2: 参数2描述
    
    Returns:
        返回值描述
    """
    # 实现逻辑
    pass
```

2. 在 `server_config.json` 中添加工具配置：

```json
{
  "name": "your_new_tool",
  "description": "工具描述",
  "category": "category_name"
}
```

### 添加新资源

1. 在 `mcp_server.py` 中添加资源处理函数：

```python
@mcp.resource("mijia://your-resource")
async def get_your_resource() -> str:
    """资源描述"""
    # 实现逻辑
    pass
```

2. 在 `server_config.json` 中添加资源配置：

```json
{
  "uri": "mijia://your-resource",
  "name": "资源名称",
  "description": "资源描述",
  "mimeType": "application/json"
}
```

## 致谢

感谢以下开源项目的支持：

- [mijia-api](https://github.com/Do1e/mijia-api) - 提供了米家设备控制的核心API实现

## 🚀 自动化发布

本项目配置了 GitHub Actions 自动化工作流：

### 📦 PyPI 自动发布

当创建新的 GitHub Release 时，会自动：
1. 构建 Python 包
2. 检查包质量
3. 发布到 PyPI

**配置步骤：**
1. 在 PyPI 创建 API Token
2. 在 GitHub 仓库设置中添加 `PYPI_API_TOKEN` Secret
3. 创建 Release 即可自动发布

详细说明请参考 [GitHub Actions 配置指南](.github/README.md)

### 🧪 持续集成测试

每次推送代码时自动：
- 在多个 Python 版本上测试
- 代码质量检查
- 包构建验证

## TODO

### 已完成功能 ✅
- [x] 连接米家云服务
- [x] 发现设备功能
- [x] 获取设备信息
- [x] 设备状态查询
- [x] 服务器状态监控

### 待开发功能 🚧
- [ ] 设备控制功能开发
  - 目前设备控制功能还未就绪
  - 需要完善设备属性设置和动作执行功能
  - 计划在后续版本中实现完整的设备控制能力

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/javen-yan/miot-mcp",
    "name": "miot-mcp",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "xiaomi, mijia, iot, smart-home, mcp, automation",
    "author": "Javen Yan",
    "author_email": "Javen Yan <2023335616@qq.com>",
    "download_url": "https://files.pythonhosted.org/packages/06/53/a9e01c9bb37e93b45a9d2be60c0e92dbe3e707ec16f605a317d9b332a1f6/miot_mcp-1.0.3.tar.gz",
    "platform": null,
    "description": "# \u7c73\u5bb6\u667a\u80fd\u8bbe\u5907 MCP \u670d\u52a1\u5668\n\n\u4e2d\u6587\u6587\u6863 | [English](README_EN.md)\n\n\u57fa\u4e8e Model Context Protocol (MCP) \u7684\u7c73\u5bb6\u667a\u80fd\u8bbe\u5907\u63a7\u5236\u670d\u52a1\u5668\uff0c\u63d0\u4f9b\u8bbe\u5907\u53d1\u73b0\u3001\u5c5e\u6027\u8bfb\u5199\u3001\u52a8\u4f5c\u8c03\u7528\u3001\u72b6\u6001\u76d1\u63a7\u7b49\u529f\u80fd\u3002\n\n## \u529f\u80fd\u7279\u6027\n\n### \ud83d\udd0c \u8fde\u63a5\u7ba1\u7406\n- \u652f\u6301\u7528\u6237\u540d\u5bc6\u7801\u767b\u5f55\n- \u652f\u6301\u4e8c\u7ef4\u7801\u767b\u5f55\n- \u81ea\u52a8\u4fdd\u5b58\u548c\u52a0\u8f7d\u8ba4\u8bc1\u4fe1\u606f\n- \u8fde\u63a5\u72b6\u6001\u76d1\u63a7\n\n### \ud83d\udcf1 \u8bbe\u5907\u7ba1\u7406\n- \u81ea\u52a8\u53d1\u73b0\u7c73\u5bb6\u8bbe\u5907\n- \u8bbe\u5907\u641c\u7d22\u548c\u8fc7\u6ee4\n- \u83b7\u53d6\u8bbe\u5907\u5c5e\u6027\u548c\u52a8\u4f5c\u5217\u8868\n- \u6279\u91cf\u64cd\u4f5c\u652f\u6301\n\n### \ud83d\udcca \u72b6\u6001\u76d1\u63a7\n- \u5b9e\u65f6\u8bbe\u5907\u72b6\u6001\u83b7\u53d6\n- \u8bbe\u5907\u72b6\u6001\u7f13\u5b58\n- \u6279\u91cf\u72b6\u6001\u5237\u65b0\n- \u72b6\u6001\u53d8\u5316\u8ffd\u8e2a\n\n### \ud83d\udee0\ufe0f \u7cfb\u7edf\u529f\u80fd\n- \u8d44\u6e90\u7f13\u5b58\u7ba1\u7406\n- \u8be6\u7ec6\u9519\u8bef\u5904\u7406\u548c\u65e5\u5fd7\n- \u670d\u52a1\u5668\u72b6\u6001\u76d1\u63a7\n- \u8fde\u901a\u6027\u6d4b\u8bd5\n\n## \u529f\u80fd\u5c55\u793a\n\n### \ud83c\udfaf \u6838\u5fc3\u529f\u80fd\n![\u529f\u80fd\u7279\u6027](static/feature.png)\n\n### \ud83d\udd0d \u8bbe\u5907\u53d1\u73b0\n![\u8bbe\u5907\u53d1\u73b0](static/discover-devices.png)\n\n### \ud83d\udcf1 \u8bbe\u5907\u4fe1\u606f\n![\u8bbe\u5907\u4fe1\u606f](static/device-info.png)\n\n### \ud83d\udee0\ufe0f \u5de5\u5177\u5217\u8868\n![\u5de5\u5177\u5217\u8868](static/tools.png)\n\n### \ud83d\udda5\ufe0f \u670d\u52a1\u5668\u72b6\u6001\n![\u670d\u52a1\u5668\u72b6\u6001](static/server-info.png)\n\n...\n\n## \u5feb\u901f\u5f00\u59cb\n\n### 1. \u5b89\u88c5\u4f9d\u8d56\n\n```bash\npip install -r requirements.txt\n```\n\n### 2. \u914d\u7f6e\u8ba4\u8bc1\u4fe1\u606f\n\n\u8bbe\u7f6e\u73af\u5883\u53d8\u91cf\uff1a\n\n```bash\nexport MIJIA_USERNAME=\"your_username\"\nexport MIJIA_PASSWORD=\"your_password\"\nexport MIJIA_ENABLE_QR=\"false\"\nexport MIJIA_LOG_LEVEL=\"INFO\"\n```\n\n### 3. \u542f\u52a8\u670d\u52a1\u5668\n\n```bash\npython mcp_server/mcp_server.py\n```\n\n### 4. \u6d4b\u8bd5\u8fde\u63a5\n\n```bash\npython mcp_test.py\n```\n\n## AI \u5de5\u5177\u96c6\u6210\n\n### Claude Desktop \u96c6\u6210\n\n\u5728 Claude Desktop \u914d\u7f6e\u6587\u4ef6\u4e2d\u6dfb\u52a0\u4ee5\u4e0b\u914d\u7f6e\uff1a\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"mijia\": {\n      \"command\": \"python\",\n      \"args\": [\"/path/to/miot-agent/mcp_server/mcp_server.py\"],\n      \"env\": {\n        \"MIJIA_USERNAME\": \"your_username\",\n        \"MIJIA_PASSWORD\": \"your_password\",\n        \"MIJIA_ENABLE_QR\": \"false\",\n        \"MIJIA_LOG_LEVEL\": \"INFO\"\n      }\n    }\n  }\n}\n```\n\n### Continue.dev \u96c6\u6210\n\n\u5728 Continue \u914d\u7f6e\u4e2d\u6dfb\u52a0\uff1a\n\n```json\n{\n  \"mcpServers\": {\n    \"mijia\": {\n      \"command\": \"python\",\n      \"args\": [\"/path/to/miot-agent/mcp_server/mcp_server.py\"],\n      \"env\": {\n        \"MIJIA_USERNAME\": \"your_username\",\n        \"MIJIA_PASSWORD\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\n### Cline \u96c6\u6210\n\n\u5bf9\u4e8e Cline\uff08\u539f Claude Dev\uff09\uff0c\u6dfb\u52a0 MCP \u670d\u52a1\u5668\u914d\u7f6e\uff1a\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"mijia\": {\n        \"command\": \"python\",\n        \"args\": [\"/path/to/miot-agent/mcp_server/mcp_server.py\"],\n        \"env\": {\n          \"MIJIA_USERNAME\": \"your_username\",\n          \"MIJIA_PASSWORD\": \"your_password\"\n        }\n      }\n    }\n  }\n}\n```\n\n### \u901a\u7528 MCP \u5ba2\u6237\u7aef\u96c6\u6210\n\n\u5bf9\u4e8e\u4efb\u4f55\u517c\u5bb9 MCP \u7684\u5ba2\u6237\u7aef\uff1a\n\n1. **\u547d\u4ee4**: `python /path/to/miot-agent/mcp_server/mcp_server.py`\n2. **\u73af\u5883\u53d8\u91cf**:\n   - `MIJIA_USERNAME`: \u7c73\u5bb6\u8d26\u6237\u7528\u6237\u540d\n   - `MIJIA_PASSWORD`: \u7c73\u5bb6\u8d26\u6237\u5bc6\u7801\n   - `MIJIA_ENABLE_QR`: \u8bbe\u7f6e\u4e3a \"true\" \u542f\u7528\u4e8c\u7ef4\u7801\u767b\u5f55\uff08\u53ef\u9009\uff09\n   - `MIJIA_LOG_LEVEL`: \u65e5\u5fd7\u7ea7\u522b\uff08DEBUG, INFO, WARNING, ERROR\uff09\n\n### \u9a8c\u8bc1\u96c6\u6210\n\n\u96c6\u6210\u5b8c\u6210\u540e\uff0c\u60a8\u5e94\u8be5\u80fd\u5728 AI \u52a9\u624b\u4e2d\u770b\u5230\u4ee5\u4e0b\u5de5\u5177\uff1a\n\n- **\u8fde\u63a5\u7ba1\u7406**: `connect`, `connect_with_qr`, `disconnect`, `ping`\n- **\u8bbe\u5907\u7ba1\u7406**: `discover_devices`, `search_devices`\n- **\u5c5e\u6027\u64cd\u4f5c**: `get_property_value`, `set_property_value`, `batch_set_properties`\n- **\u52a8\u4f5c\u64cd\u4f5c**: `call_action`\n- **\u72b6\u6001\u76d1\u63a7**: `get_device_status`, `refresh_all_device_status`\n- **\u5bb6\u5ead\u7ba1\u7406**: `get_homes`, `get_consumable_items`\n- **\u573a\u666f\u7ba1\u7406**: `get_scenes_list`, `run_scene`\n- **\u7cfb\u7edf\u7ba1\u7406**: `get_server_status`, `clear_cache`\n\n\u4ee5\u53ca\u8fd9\u4e9b\u8d44\u6e90\uff1a\n- `mijia://devices` - \u8bbe\u5907\u5217\u8868\n- `mijia://config` - \u914d\u7f6e\u4fe1\u606f\n- `mijia://device/{device_id}/properties` - \u8bbe\u5907\u5c5e\u6027\n- `mijia://device/{device_id}/actions` - \u8bbe\u5907\u52a8\u4f5c\n\n## \u5de5\u5177\u4f7f\u7528\u6307\u5357\n\n### \u8fde\u63a5\u7ba1\u7406\n\n#### \u8fde\u63a5\u5230\u7c73\u5bb6\u4e91\u670d\u52a1\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"connect\",\n    \"arguments\": {}\n  }\n}\n```\n\n#### \u65ad\u5f00\u8fde\u63a5\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"disconnect\",\n    \"arguments\": {}\n  }\n}\n```\n\n### \u8bbe\u5907\u53d1\u73b0\u548c\u7ba1\u7406\n\n#### \u53d1\u73b0\u8bbe\u5907\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"discover_devices\",\n    \"arguments\": {}\n  }\n}\n```\n\n#### \u641c\u7d22\u8bbe\u5907\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"search_devices\",\n    \"arguments\": {\n      \"name_filter\": \"\u53f0\u706f\",\n      \"model_filter\": \"xiaomi\",\n      \"online_only\": true\n    }\n  }\n}\n```\n\n### \u8bbe\u5907\u5c5e\u6027\u64cd\u4f5c\n\n#### \u83b7\u53d6\u8bbe\u5907\u5c5e\u6027\u5217\u8868\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_device_properties\",\n    \"arguments\": {\n      \"device_id\": \"123456789\"\n    }\n  }\n}\n```\n\n#### \u83b7\u53d6\u5c5e\u6027\u503c\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_property_value\",\n    \"arguments\": {\n      \"device_id\": \"123456789\",\n      \"siid\": 2,\n      \"piid\": 1\n    }\n  }\n}\n```\n\n#### \u8bbe\u7f6e\u5c5e\u6027\u503c\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"set_property_value\",\n    \"arguments\": {\n      \"device_id\": \"123456789\",\n      \"siid\": 2,\n      \"piid\": 1,\n      \"value\": true\n    }\n  }\n}\n```\n\n#### \u6279\u91cf\u8bbe\u7f6e\u5c5e\u6027\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"batch_set_properties\",\n    \"arguments\": {\n      \"operations\": [\n        {\n          \"device_id\": \"123456789\",\n          \"siid\": 2,\n          \"piid\": 1,\n          \"value\": true\n        },\n        {\n          \"device_id\": \"987654321\",\n          \"siid\": 3,\n          \"piid\": 2,\n          \"value\": 50\n        }\n      ]\n    }\n  }\n}\n```\n\n### \u8bbe\u5907\u52a8\u4f5c\u8c03\u7528\n\n#### \u83b7\u53d6\u8bbe\u5907\u52a8\u4f5c\u5217\u8868\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_device_actions\",\n    \"arguments\": {\n      \"device_id\": \"123456789\"\n    }\n  }\n}\n```\n\n#### \u8c03\u7528\u8bbe\u5907\u52a8\u4f5c\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"call_action\",\n    \"arguments\": {\n      \"device_id\": \"123456789\",\n      \"siid\": 2,\n      \"aiid\": 1,\n      \"params\": []\n    }\n  }\n}\n```\n\n### \u72b6\u6001\u76d1\u63a7\n\n#### \u83b7\u53d6\u8bbe\u5907\u72b6\u6001\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_device_status\",\n    \"arguments\": {\n      \"device_id\": \"123456789\"\n    }\n  }\n}\n```\n\n#### \u5237\u65b0\u6240\u6709\u8bbe\u5907\u72b6\u6001\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"refresh_all_device_status\",\n    \"arguments\": {}\n  }\n}\n```\n\n#### \u83b7\u53d6\u7f13\u5b58\u72b6\u6001\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_cached_device_status\",\n    \"arguments\": {\n      \"device_id\": \"123456789\"\n    }\n  }\n}\n```\n\n### \u7cfb\u7edf\u7ba1\u7406\n\n#### \u83b7\u53d6\u670d\u52a1\u5668\u72b6\u6001\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_server_status\",\n    \"arguments\": {}\n  }\n}\n```\n\n#### \u6e05\u9664\u7f13\u5b58\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"clear_cache\",\n    \"arguments\": {}\n  }\n}\n```\n\n#### \u6d4b\u8bd5\u8fde\u901a\u6027\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"ping\",\n    \"arguments\": {\n      \"message\": \"hello\"\n    }\n  }\n}\n```\n\n### \u5bb6\u5ead\u548c\u573a\u666f\u7ba1\u7406\n\n#### \u83b7\u53d6\u5bb6\u5ead\u5217\u8868\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_homes\",\n    \"arguments\": {}\n  }\n}\n```\n\n#### \u83b7\u53d6\u573a\u666f\u5217\u8868\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_scenes_list\",\n    \"arguments\": {\n      \"home_id\": \"123456789\"\n    }\n  }\n}\n```\n\n#### \u6267\u884c\u573a\u666f\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"run_scene\",\n    \"arguments\": {\n      \"scene_id\": \"987654321\"\n    }\n  }\n}\n```\n\n#### \u83b7\u53d6\u8017\u6750\u4fe1\u606f\n```json\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_consumable_items\",\n    \"arguments\": {\n      \"home_id\": \"123456789\",\n      \"owner_id\": 12345\n    }\n  }\n}\n```\n\n## \u8d44\u6e90\u8bbf\u95ee\n\n### \u83b7\u53d6\u8bbe\u5907\u5217\u8868\n```json\n{\n  \"method\": \"resources/read\",\n  \"params\": {\n    \"uri\": \"mijia://devices\"\n  }\n}\n```\n\n### \u83b7\u53d6\u914d\u7f6e\u4fe1\u606f\n```json\n{\n  \"method\": \"resources/read\",\n  \"params\": {\n    \"uri\": \"mijia://config\"\n  }\n}\n```\n\n### \u83b7\u53d6\u8bbe\u5907\u5c5e\u6027\n```json\n{\n  \"method\": \"resources/read\",\n  \"params\": {\n    \"uri\": \"mijia://device/123456789/properties\"\n  }\n}\n```\n\n### \u83b7\u53d6\u8bbe\u5907\u52a8\u4f5c\n```json\n{\n  \"method\": \"resources/read\",\n  \"params\": {\n    \"uri\": \"mijia://device/123456789/actions\"\n  }\n}\n```\n\n## \u9519\u8bef\u5904\u7406\n\n\u6240\u6709\u5de5\u5177\u8c03\u7528\u90fd\u4f1a\u8fd4\u56de\u7edf\u4e00\u7684\u9519\u8bef\u683c\u5f0f\uff1a\n\n```json\n{\n  \"success\": false,\n  \"error\": \"\u9519\u8bef\u63cf\u8ff0\",\n  \"error_code\": \"ERROR_CODE\",\n  \"timestamp\": \"2024-01-01T12:00:00Z\"\n}\n```\n\n\u5e38\u89c1\u9519\u8bef\u4ee3\u7801\uff1a\n- `ADAPTER_NOT_INITIALIZED`: \u9002\u914d\u5668\u672a\u521d\u59cb\u5316\n- `DEVICE_NOT_FOUND`: \u8bbe\u5907\u672a\u627e\u5230\n- `PROPERTY_NOT_FOUND`: \u5c5e\u6027\u672a\u627e\u5230\n- `ACTION_NOT_FOUND`: \u52a8\u4f5c\u672a\u627e\u5230\n- `CONNECTION_FAILED`: \u8fde\u63a5\u5931\u8d25\n- `AUTHENTICATION_FAILED`: \u8ba4\u8bc1\u5931\u8d25\n\n## \u65e5\u5fd7\u914d\u7f6e\n\n\u65e5\u5fd7\u7ea7\u522b\u53ef\u4ee5\u901a\u8fc7\u73af\u5883\u53d8\u91cf\u8bbe\u7f6e\uff1a\n\n```bash\n# \u73af\u5883\u53d8\u91cf\nexport MIJIA_LOG_LEVEL=\"DEBUG\"\n```\n\n## \u9879\u76ee\u7ed3\u6784\n\n```\nmiot-agent/\n\u251c\u2500\u2500 adapter/\n\u2502   \u251c\u2500\u2500 mijia_adapter.py      # \u7c73\u5bb6\u9002\u914d\u5668\u5b9e\u73b0\n\u2502   \u2514\u2500\u2500 mijia_config.py       # \u914d\u7f6e\u7ba1\u7406\n\u251c\u2500\u2500 mcp_server/\n\u2502   \u251c\u2500\u2500 mcp_server.py         # MCP\u670d\u52a1\u5668\u4e3b\u7a0b\u5e8f\n\u2502   \u2514\u2500\u2500 server_config.json    # \u670d\u52a1\u5668\u914d\u7f6e\n\u251c\u2500\u2500 requirements.txt          # \u9879\u76ee\u4f9d\u8d56\n\u251c\u2500\u2500 mcp_test.py              # \u6d4b\u8bd5\u811a\u672c\n\u2514\u2500\u2500 README.md                # \u9879\u76ee\u6587\u6863\n```\n\n## \u5f00\u53d1\u6307\u5357\n\n### \u6dfb\u52a0\u65b0\u5de5\u5177\n\n1. \u5728 `mcp_server.py` \u4e2d\u6dfb\u52a0\u5de5\u5177\u51fd\u6570\uff1a\n\n```python\n@mcp.tool()\nasync def your_new_tool(param1: str, param2: int = 0) -> str:\n    \"\"\"\u5de5\u5177\u63cf\u8ff0\n    \n    Args:\n        param1: \u53c2\u65701\u63cf\u8ff0\n        param2: \u53c2\u65702\u63cf\u8ff0\n    \n    Returns:\n        \u8fd4\u56de\u503c\u63cf\u8ff0\n    \"\"\"\n    # \u5b9e\u73b0\u903b\u8f91\n    pass\n```\n\n2. \u5728 `server_config.json` \u4e2d\u6dfb\u52a0\u5de5\u5177\u914d\u7f6e\uff1a\n\n```json\n{\n  \"name\": \"your_new_tool\",\n  \"description\": \"\u5de5\u5177\u63cf\u8ff0\",\n  \"category\": \"category_name\"\n}\n```\n\n### \u6dfb\u52a0\u65b0\u8d44\u6e90\n\n1. \u5728 `mcp_server.py` \u4e2d\u6dfb\u52a0\u8d44\u6e90\u5904\u7406\u51fd\u6570\uff1a\n\n```python\n@mcp.resource(\"mijia://your-resource\")\nasync def get_your_resource() -> str:\n    \"\"\"\u8d44\u6e90\u63cf\u8ff0\"\"\"\n    # \u5b9e\u73b0\u903b\u8f91\n    pass\n```\n\n2. \u5728 `server_config.json` \u4e2d\u6dfb\u52a0\u8d44\u6e90\u914d\u7f6e\uff1a\n\n```json\n{\n  \"uri\": \"mijia://your-resource\",\n  \"name\": \"\u8d44\u6e90\u540d\u79f0\",\n  \"description\": \"\u8d44\u6e90\u63cf\u8ff0\",\n  \"mimeType\": \"application/json\"\n}\n```\n\n## \u81f4\u8c22\n\n\u611f\u8c22\u4ee5\u4e0b\u5f00\u6e90\u9879\u76ee\u7684\u652f\u6301\uff1a\n\n- [mijia-api](https://github.com/Do1e/mijia-api) - \u63d0\u4f9b\u4e86\u7c73\u5bb6\u8bbe\u5907\u63a7\u5236\u7684\u6838\u5fc3API\u5b9e\u73b0\n\n## \ud83d\ude80 \u81ea\u52a8\u5316\u53d1\u5e03\n\n\u672c\u9879\u76ee\u914d\u7f6e\u4e86 GitHub Actions \u81ea\u52a8\u5316\u5de5\u4f5c\u6d41\uff1a\n\n### \ud83d\udce6 PyPI \u81ea\u52a8\u53d1\u5e03\n\n\u5f53\u521b\u5efa\u65b0\u7684 GitHub Release \u65f6\uff0c\u4f1a\u81ea\u52a8\uff1a\n1. \u6784\u5efa Python \u5305\n2. \u68c0\u67e5\u5305\u8d28\u91cf\n3. \u53d1\u5e03\u5230 PyPI\n\n**\u914d\u7f6e\u6b65\u9aa4\uff1a**\n1. \u5728 PyPI \u521b\u5efa API Token\n2. \u5728 GitHub \u4ed3\u5e93\u8bbe\u7f6e\u4e2d\u6dfb\u52a0 `PYPI_API_TOKEN` Secret\n3. \u521b\u5efa Release \u5373\u53ef\u81ea\u52a8\u53d1\u5e03\n\n\u8be6\u7ec6\u8bf4\u660e\u8bf7\u53c2\u8003 [GitHub Actions \u914d\u7f6e\u6307\u5357](.github/README.md)\n\n### \ud83e\uddea \u6301\u7eed\u96c6\u6210\u6d4b\u8bd5\n\n\u6bcf\u6b21\u63a8\u9001\u4ee3\u7801\u65f6\u81ea\u52a8\uff1a\n- \u5728\u591a\u4e2a Python \u7248\u672c\u4e0a\u6d4b\u8bd5\n- \u4ee3\u7801\u8d28\u91cf\u68c0\u67e5\n- \u5305\u6784\u5efa\u9a8c\u8bc1\n\n## TODO\n\n### \u5df2\u5b8c\u6210\u529f\u80fd \u2705\n- [x] \u8fde\u63a5\u7c73\u5bb6\u4e91\u670d\u52a1\n- [x] \u53d1\u73b0\u8bbe\u5907\u529f\u80fd\n- [x] \u83b7\u53d6\u8bbe\u5907\u4fe1\u606f\n- [x] \u8bbe\u5907\u72b6\u6001\u67e5\u8be2\n- [x] \u670d\u52a1\u5668\u72b6\u6001\u76d1\u63a7\n\n### \u5f85\u5f00\u53d1\u529f\u80fd \ud83d\udea7\n- [ ] \u8bbe\u5907\u63a7\u5236\u529f\u80fd\u5f00\u53d1\n  - \u76ee\u524d\u8bbe\u5907\u63a7\u5236\u529f\u80fd\u8fd8\u672a\u5c31\u7eea\n  - \u9700\u8981\u5b8c\u5584\u8bbe\u5907\u5c5e\u6027\u8bbe\u7f6e\u548c\u52a8\u4f5c\u6267\u884c\u529f\u80fd\n  - \u8ba1\u5212\u5728\u540e\u7eed\u7248\u672c\u4e2d\u5b9e\u73b0\u5b8c\u6574\u7684\u8bbe\u5907\u63a7\u5236\u80fd\u529b\n\n## \u8bb8\u53ef\u8bc1\n\nMIT License\n\n## \u8d21\u732e\n\n\u6b22\u8fce\u63d0\u4ea4 Issue \u548c Pull Request\uff01\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Mijia smart device MCP server, providing device discovery, property read/write, action invoke and other functions",
    "version": "1.0.3",
    "project_urls": {
        "Bug Reports": "https://github.com/javen-yan/miot-mcp/issues",
        "Documentation": "https://github.com/javen-yan/miot-mcp#readme",
        "Homepage": "https://github.com/javen-yan/miot-mcp",
        "Source": "https://github.com/javen-yan/miot-mcp"
    },
    "split_keywords": [
        "xiaomi",
        " mijia",
        " iot",
        " smart-home",
        " mcp",
        " automation"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8bb75feb38941cdd767f7c37748f01fa292a687814fc529dcff113412f4cd8c1",
                "md5": "33e78d9b539f1f77503ef45f7aec407d",
                "sha256": "5440b44246566dbf432dca8603252631ff27cc49c573ba73555f855d4c0c6dfd"
            },
            "downloads": -1,
            "filename": "miot_mcp-1.0.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "33e78d9b539f1f77503ef45f7aec407d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 24525,
            "upload_time": "2025-08-22T10:21:40",
            "upload_time_iso_8601": "2025-08-22T10:21:40.298258Z",
            "url": "https://files.pythonhosted.org/packages/8b/b7/5feb38941cdd767f7c37748f01fa292a687814fc529dcff113412f4cd8c1/miot_mcp-1.0.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "0653a9e01c9bb37e93b45a9d2be60c0e92dbe3e707ec16f605a317d9b332a1f6",
                "md5": "cd3637d9299f2fccc3e3be4677e944f5",
                "sha256": "6a8f20ab0d0752dc79319f7171c13fecf815fad268fd0d2ea87a467d1eef3101"
            },
            "downloads": -1,
            "filename": "miot_mcp-1.0.3.tar.gz",
            "has_sig": false,
            "md5_digest": "cd3637d9299f2fccc3e3be4677e944f5",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 28474,
            "upload_time": "2025-08-22T10:21:41",
            "upload_time_iso_8601": "2025-08-22T10:21:41.467284Z",
            "url": "https://files.pythonhosted.org/packages/06/53/a9e01c9bb37e93b45a9d2be60c0e92dbe3e707ec16f605a317d9b332a1f6/miot_mcp-1.0.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-22 10:21:41",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "javen-yan",
    "github_project": "miot-mcp",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "mcp",
            "specs": [
                [
                    ">=",
                    "1.13.0"
                ]
            ]
        },
        {
            "name": "mijiaAPI",
            "specs": [
                [
                    ">=",
                    "2.0.1"
                ]
            ]
        },
        {
            "name": "Pillow",
            "specs": [
                [
                    ">=",
                    "10.0.0"
                ]
            ]
        },
        {
            "name": "setuptools",
            "specs": [
                [
                    ">=",
                    "80.9.0"
                ]
            ]
        }
    ],
    "lcname": "miot-mcp"
}