🔍🐛 家庭助理诊断MCP服务器🏠🔧
人工智能家居助理诊断和健康监测
专为拥抱面孔MCP的第一个生日黑客马拉松2025而建
🎥 演示
💡 为什么存在
Home Assistant是运行智能家居的强大平台，但当某些东西停止工作时，诊断问题可能会让人头疼。手动检查数百个实体、下载日志或试图向无法直接看到系统的AI解释问题都令人沮丧。
此MCP服务器允许您最喜欢的LLM直接访问诊断工具，使其能够自主排除您的Home Assistant实例的故障，而无需您手动收集信息。
不再在黑暗中调试。让AI成为你的智能家居医生。
🎯 此MCP服务器的功能
完整的模型上下文协议（MCP）服务器提供 39种专用诊断工具, 13诊断资源，以及 4个AI提示 让AI助手分析、排除故障和维护家庭助理安装。
🏆 签名功能
🌐 高级网络分析
- 基于LQI/RSSI分布的Zigbee网状健康评分（0-100）
- 具有严重性级别的弱链接检测
- 孤儿设备识别
- 路由器放置建议
🧹 智能清理智能
- 孤立实体检测-查找未在任何地方使用的实体
- 使用统计-引用最多/最少的实体
- 使用安全删除建议清理优先级
- 基于域的分组，用于有组织的清理
🤖 自动化安全分析仪
- 种族状况检测-同一实体上的多个自动化
- 无限循环预防-循环自动化依赖
- 冲突动作检测
- 不安全模式警告
⚡ 能源与成本情报
- 设备级细分能耗跟踪
- 每月预测的成本估算
- 顶级消费者识别
- 节能建议
🔍 全系统诊断
- 健康评分（0-100%）和严重程度评估
- 具有置信水平的根本原因分析
- 实时异常检测
- 自动问题分类（低/中/高/关键）
🔧 安全自动修复
- 具有风险评估的自动维修
- 安全操作无需确认
- 前后快照以提高透明度
📊 高级监控
- 带有关键警报的电池健康跟踪
- 传感器老化检测
- 网络连接监控
- 历史统计与趋势分析
🎯 物理设备管理
- 闪光/蜂鸣设备识别
- ZHA设备网格可视化
- ESPHome设备监控
- 制造商离线设备检测
🛠️ 包含内容
39诊断工具
核心诊断（16个工具）
get_version-家庭助理版本信息battery_report-电池电量和严重警报find_unavailable_entities-检测不可用实体find_stale_entities-查找未更新的传感器find_anomalous_entities-检测不可能/冻结的值offline_devices_report-设备完全离线get_repair_items-房委会维修小组问题get_error_log-错误和警告分析diagnose_issue-使用AI进行深度实体诊断diagnose_automation-自动化故障排除diagnose_system-完成系统健康检查audit_zigbee_mesh-具有LQI/RSSI的Zigbee网状健康find_orphan_entities-检测未使用的实体detect_automation_conflicts-比赛条件和循环energy_consumption_report-能源跟踪和成本entity_dependency_graph-实体关系
系统监控（6个工具）
get_system_health-CPU、内存、磁盘、监控器get_network_info-网络配置get_update_status-可用更新list_integrations-已加载集成system_overview-完整的系统概述get_zha_devices-具有网状质量的Zigbee设备
实体管理（13种工具）
list_automations-所有带有状态的自动化list_entities-使用筛选器查询实体domain_summary_tool-域名统计search_entities_tool-语义搜索get_entity-实体状态（基本/详细）get_entity_statistics-历史分析get_history-状态更改历史entity_action-控制实体（开/关/切换）call_service_tool-低级别HA服务呼叫identify_device-物理上的闪光/蜂鸣设备recent_activity-近期活动get_esphome_devices-ESPHome设备状态get_addons-附加组件状态和更新
维护（6个工具）
reload_core_config-重新加载HA配置reload_scripts-重新加载脚本定义auto_fix-自动安全维修restart_ha-重新启动家庭助理
13诊断资源
健康与系统资源
ha://diagnostics/health-score-系统健康状况（降价）ha://diagnostics/health-score/json-系统健康状况（JSON）ha://diagnostics/system-完整系统报告（降价）ha://diagnostics/system/json-完整系统报告（JSON）ha://diagnostics/zigbee-mesh-Zigbee网格健康与ASCIIha://diagnostics/system-health-完成健康审计
实体资源
ha://diagnostics/entity/{entity_id}-实体诊断（降价）ha://diagnostics/entity/{entity_id}/json-实体诊断（JSON）ha://entities-所有实体概述ha://entities/{entity_id}-单一实体ha://entities/{entity_id}/detailed-具有完整属性的实体ha://entities/domain/{domain}-按域列出的实体ha://search/{query}/{limit}-实体搜索结果
4个AI提示
诊断工作流程的交互式对话模板：
debug_automation-调试自动化未触发troubleshoot_entity-解决实体问题automation_health_check-查找冲突和改进diagnose_everything- 终极诊断编排器
特色：诊断_一切
在一个命令中完成系统审核：
🏥 COMPLETE DIAGNOSTIC PROTOCOL:
├─ System-Wide Analysis (diagnose_system)
├─ Zigbee Mesh Audit (audit_zigbee_mesh)
├─ Entity Usage Analysis (find_orphan_entities)
├─ Automation Safety Check (detect_automation_conflicts)
├─ Energy Consumption (energy_consumption_report)
└─ Dependency Mapping (entity_dependency_graph)
📊 OUTPUT:
✅ Overall health score (0-100)
✅ Issues by severity & category
✅ Actionable recommendations
✅ Auto-fix opportunities🚀 安装
先决条件
- Python 3.13+
- 家庭助理实例
- 长寿命访问令牌
快速开始
# Clone repository
git clone https://github.com/burgueishon/Home-Assistant-Diagnostics-MCP-Server.git
cd Home-Assistant-Diagnostics-MCP-Server
# Install with uv (recommended)
uv venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
uv pip install -e .
# Or use pip
python -m venv .venv
source .venv/bin/activate
pip install -e .配置
获取家庭助理令牌：
- 转到：家庭助理→ 个人资料→ 安全
- 创建“长期访问令牌”
- 复制令牌（您将在下一步中使用它）
🔧 用法
克劳德桌面
编辑配置文件：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"home-assistant-diagnostics": {
"command": "uv",
"args": ["run", "home-assistant-diagnostics-mcp"],
"cwd": "/absolute/path/to/Home-Assistant-Diagnostics-MCP-Server",
"env": {
"HA_URL": "http://YOUR_HA_IP:8123",
"HA_TOKEN": "your-long-lived-token"
}
}
}
}克劳德代码
# From project directory
claude mcp add --transport stdio \
-e HA_URL=http://YOUR_HA_IP:8123 \
-e HA_TOKEN=your-long-lived-token \
-- home-assistant-diagnostics uv run home-assistant-diagnostics-mcp替换 YOUR_HA_IP 使用您的家庭助理IP/主机名和 your-long-lived-token 用你真正的代币。
VS Code
创建 .vscode/mcp.json:
{
"servers": {
"home-assistant-diagnostics": {
"command": "uv",
"args": ["run", "home-assistant-diagnostics-mcp"],
"cwd": "/absolute/path/to/Home-Assistant-Diagnostics-MCP-Server",
"env": {
"HA_URL": "http://YOUR_HA_IP:8123",
"HA_TOKEN": "your-long-lived-token"
}
}
}
}光标IDE
添加到光标设置：
{
"mcp": {
"servers": {
"home-assistant-diagnostics": {
"command": "uv",
"args": ["run", "home-assistant-diagnostics-mcp"],
"cwd": "/absolute/path/to/Home-Assistant-Diagnostics-MCP-Server",
"env": {
"HA_URL": "http://YOUR_HA_IP:8123",
"HA_TOKEN": "your-long-lived-token"
}
}
}
}
}💬 查询示例
完整的系统健康状况
- *“运行完整的系统诊断”*
- *“我的家庭助理怎么了？”*
- *“给我做一次全面的健康检查”*
网络和Zigbee分析
- *“审核我的Zigbee网状网络”*
- *“显示Zigbee健康评分和弱设备”*
- *“哪些设备需要更好的路由器放置？”*
智能清理
- *“查找我可以安全删除的所有孤立实体”*
- *“检测自动化冲突和竞争条件”*
- *“显示按域组织的未使用实体”*
能源监测
- *“显示过去24小时的能耗”*
- *“哪些设备消耗的能量最多？”*
- *“估算我的每月电费”*
快速诊断
- *“哪些电池电量低？”*
- *“显示所有不可用的实体”*
- *“查找6小时内未更新的传感器”*
自动化调试
- *“为什么我的厨房自动化不起作用？”*
- *“诊断自动化.低电池通知”*
- *“检查自动化冲突”*
设备管理
- *“识别卧室灯”* （闪烁设备）
- *“哪些Zigbee设备信号较弱？”*
- *“列出所有脱机设备”*
系统监控
- *“检查错误日志中的问题”*
- *“加载了哪些集成？”*
- *“有可用的更新吗？”*
🏗️ 项目结构
Home-Assistant-Diagnostics-MCP-Server/
├── app/
│ ├── server.py # FastMCP server (39 tools, 13 resources, 4 prompts)
│ ├── ha.py # Home Assistant API client
│ ├── run.py # Entry point
│ ├── config.py # Configuration management
│ └── __main__.py # Module execution
├── tests/
│ ├── __init__.py
│ └── test_smoke.py # Smoke tests
├── .gitignore
├── LICENSE # MIT License
├── README.md # This file
├── pyproject.toml # Project dependencies
└── uv.lock # Dependency lock file🤝 贡献
专为 拥抱面孔MCP的第一个生日黑客马拉松2025
欢迎投稿！拜托：
- 复刻仓库
- 创建要素分支
- 进行更改
- 提交拉取请求
📝 许可证
MIT许可证-有关详细信息，请参阅许可证文件
🙏 致谢
- 拥抱脸 -MCP的第一个生日黑客马拉松2025组织者
- FastMCP -优秀的MCP框架
- 家庭助手 -惊人的开源家庭自动化平台
🔗 链接
______________________________________________________________________
内置于❤️ 面向家庭助理和人工智能社区
*通过AI驱动的诊断使智能家居更智能*