Home Assistant MCP服务器

一个强大的Model Context Protocol (MCP)服务器,提供完整的Web界面,用于将Home Assistant与AI代理集成,支持设备管理、自动化控制及HTTP REST API服务。

  • by Jonathan97480
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Jonathan97480/McpHomeAssistant

使用说明

🏠 家庭助理MCP服务器

强大的模型上下文协议(MCP)服务器 完整的web界面 将Home Assistant与AI代理集成。

完整的web界面! 阶段3.4包括一个响应式web界面,包括仪表板、身份验证、权限管理和Home Assistant多实例配置。Raspberry Pi的自动安装。

🍓 Raspberry Pi准备好了! 使用自动脚本优化Raspberry Pi 3b+安装 install.sh.

🇫🇷 法文版 | 📚 文档 | 🧪 测试

✨ 特性

  • 🏠 实体管理 :读取所有家庭助理设备的状态
  • 🎮 设备控制 :打开/关闭灯、开关等
  • 📊 历史访问 :访问传感器和实体历史数据
  • 🔐 安全认证 :使用家庭助理访问令牌
  • 🚀 高性能 :异步连接可实现最佳响应
  • 🛠️ 服务呼叫 :致电任何家庭助理服务
  • 🤖 智能自动化 :生成智能YAML自动化

🌐 HTTP服务器模式

除了MCP协议外,此服务器还可以作为独立的HTTP REST API服务器运行,非常适合:

  • 🍓 Raspberry Pi部署 与家庭助理一起
  • 🔗 Web应用程序 以及自定义集成
  • 🚀 微服务 建筑
  • 📱 移动应用 第三方工具
  • 🤖 AI代理 不直接支持MCP协议

为什么使用HTTP服务器模式?

  • 通用兼容性:任何编程语言或工具都可以通过HTTP连接
  • 直接部署:直接安装在运行Home Assistant的Raspberry Pi上
  • 无需MCP客户端:适用于任何HTTP客户端(curl、Postman、web浏览器)
  • REST API标准:易于与现有系统和工作流程集成
  • 独立操作:不需要MCP基础设施的独立服务

HTTP端点

HTTP服务器为Home Assistant提供完整的REST API接口:

  • GET /health -服务器健康检查和家庭助理连接状态
  • GET /api/entities -列出所有实体(可选域过滤,如 ?domain=light)
  • GET /api/entities/{entity_id} -获取特定实体状态和属性
  • POST /api/services/call -呼叫总部助理服务(打开/关闭设备等)
  • GET /api/history -通过时间范围过滤获取实体历史数据

使用案例:

  • Web仪表板:为Home Assistant构建自定义web界面
  • 移动应用:使用HTTP API创建本机移动应用程序
  • 自动化脚本:使用任何编程语言实现家居自动化
  • 第三方集成:将非MCP服务连接到家庭助理
  • 开发测试:卷曲或Postman快速API测试

快速安装

自动安装:

curl -fsSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash

手动安装:

git clone https://github.com/Jonathan97480/McpHomeAssistant.git
cd McpHomeAssistant
chmod +x install.sh
./install.sh

快速启动HTTP服务器

# Install dependencies
pip install aiohttp python-dotenv

# Configure environment
cp .env.example .env
# Edit .env with your Home Assistant URL and token

# Start HTTP server
python http_server.py

服务器在上运行 http://localhost:3002 默认情况下,并提供完整的REST API接口。

API调用示例:

# Check server health
curl http://localhost:3002/health

# List all lights
curl http://localhost:3002/api/entities?domain=light

# Turn on a light
curl -X POST http://localhost:3002/api/services/call \
  -H "Content-Type: application/json" \
  -d '{"domain": "light", "service": "turn_on", "target": {"entity_id": "light.living_room"}}'

📖 完整的HTTP服务器指南

🎯 HTTP与MCP:什么时候使用哪个?

在以下情况下使用HTTP服务器:

  • 🍓 直接安装在Raspberry Pi 3B上+
  • 🌐 构建web应用程序或移动应用程序
  • 🔧 与非MCP工具和服务集成
  • 🚀 需要跨编程语言的通用兼容性
  • 📊 创建自定义仪表板或监控系统

在以下情况下使用MCP服务器:

  • 💻 与支持MCP的AI代理(Claude Desktop等)合作
  • 🤖 需要基于工具的结构化交互
  • 🔄 想要自动工具发现和模式验证
  • 📝 更喜欢基于对话的设备控制

📁 项目结构

homeassistant-mcp-server/
├── src/                              # Main source code
│   └── homeassistant_mcp_server/
│       └── server.py                 # Main MCP server
├── tests/                            # Test and analysis scripts
│   ├── test_connection.py            # Basic connection test
│   ├── test_mcp_tools.py             # Complete tools test
│   ├── test_http_server.py           # HTTP server tests
│   ├── analyze_energy.py             # Energy analysis
│   └── analyze_smart_plugs.py        # Smart plugs analysis
├── examples/                         # Examples and configuration
│   ├── claude_desktop_config.json    # Claude Desktop configuration
│   └── smart_plug_automations.py     # Smart plug automations
├── docs/                             # Documentation
│   ├── QUICKSTART.md                 # Quick start guide
│   ├── HTTP_SERVER_README.md         # HTTP server documentation
│   ├── RASPBERRY_PI_INSTALL.md       # Raspberry Pi installation
│   └── ARCHITECTURE.md               # Technical architecture
├── scripts/                          # Utility scripts
│   ├── launcher.py                   # Service launcher wrapper
│   └── README.md                     # Scripts documentation
├── http_server.py                    # Standalone HTTP server
├── install.sh                        # Raspberry Pi installation script
├── .env.example                      # Configuration example
└── README.md                         # This file

🚀 安装

快速启动选项

🍓 Raspberry Pi安装(推荐)

直接安装在Raspberry Pi 3B+和家庭助理上:

# Download and run the installation script
curl -sSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash

# Or download and customize before running
wget https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh
chmod +x install.sh
./install.sh

🎯 针对Raspberry Pi 3B+进行了优化:

  • ✅ HTTP服务器设置:安装独立的HTTP服务器,便于AI集成
  • ✅ 交互式配置:安装过程中提示输入Home Assistant令牌和URL
  • ✅ 系统化服务:自动配置系统服务以自动启动
  • ✅ 安全:适当的文件权限和服务隔离
  • ✅ 端口3002:可从外部计算机访问的HTTP REST API
  • ✅ 资源优化:适用于Pi 3B+硬件的轻量级部署
  • ✅ Debian兼容:在Raspberry Pi OS(基于Debian)上测试

系统要求:

  • Raspberry Pi 3B+或更新版本
  • Raspberry Pi操作系统(建议使用Debian 11+)
  • 在同一个Pi或网络上运行的家庭助手
  • Python 3.9+(必要时自动安装)
  • 至少512MB可用RAM

📖 完整的Raspberry Pi指南

💻 桌面安装

对于开发或远程安装:

先决条件

  • Python 3.8+
  • 启用API的家庭助手
  • 家庭助理访问令牌

服务器安装

cd homeassistant-mcp-server
pip install -e .

配置

  1. 创建一个 .env 文件:
HASS_URL=http://192.168.1.22:8123
HASS_TOKEN=your_token_here
  1. 获取您的家庭助理令牌:
    • 前往Home Assistant>个人资料>长期访问令牌
    • 创建新令牌
    • 复制到 .env 文件

Claude桌面配置

将此添加到您的Claude Desktop配置中(claude_desktop_config.json):

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

📄 完整的配置文件可在 examples/claude_desktop_config.json

🤖 AI服务配置

克劳德桌面版

将此添加到您的Claude Desktop配置中(claude_desktop_config.json):

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

LM工作室

在LM Studio中配置MCP:

  1. 打开LM工作室
  2. 前往“设置”>“MCP服务器”
  3. 添加新服务器:
    • 名字: homeassistant
    • 命令: homeassistant-mcp-server
    • 环境变量:
      HASS_URL=http://192.168.1.22:8123
      HASS_TOKEN=your_token_here
      

Continue.dev(VS代码扩展)

添加到“继续”配置(.continue/config.json):

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

光标IDE

添加到Cursor的AI配置:

  1. 打开光标IDE
  2. 前往“设置”>“AI”>“MCP服务器”
  3. 添加服务器配置:
    {
      "name": "homeassistant",
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
    

Cline(VS代码扩展)

在临床设置中配置:

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "args": [],
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

LM工作室

LM Studio可以通过自定义HTTP功能使用服务器:

选项1:HTTP函数(推荐)

  1. 导入文件 configs/lm-studio-functions.json
  2. 使用提示系统 configs/lm-studio-system-prompt.md
  3. 确保HTTP服务器正在运行: http://192.168.1.22:3002/health

配置快速:

{
  "name": "control_light",
  "endpoint": {
    "method": "POST",
    "url": "http://192.168.1.22:3002/api/services/call",
    "body": {
      "domain": "light",
      "service": "{{action}}",
      "service_data": {"entity_id": "{{entity_id}}"}
    }
  }
}

📖 LM工作室指南 }


### OpenWebUI
For OpenWebUI MCP integration:

1. Install the MCP plugin
2. Configure server in settings:
   ```yaml
   servers:
     homeassistant:
       command: homeassistant-mcp-server
       env:
         HASS_URL: "http://192.168.1.22:8123"
         HASS_TOKEN: "your_token_here"

自定义集成

对于其他MCP兼容服务,请使用以下标准格式:

{
  "servers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

🔧 配置说明:

  • 替换 your_token_here 使用您实际的家庭助理令牌
  • 如果您的家庭助理在其他地址上运行,请更新URL
  • 某些服务可能需要可执行文件的完整路径
  • 添加配置后重新启动AI服务

🧪 测试与验证

使用提供的脚本测试您的安装:

# Test Home Assistant connection
python tests/test_connection.py

# Complete test of all MCP tools
python tests/test_mcp_tools.py

# Analyze your energy consumption
python tests/analyze_energy.py

# Analyze your smart plugs
python tests/analyze_smart_plugs.py

# Generate example automations
python examples/smart_plug_automations.py

💬 用法

配置后,您可以询问Claude:

  • “现在什么灯亮着?”
  • “把客厅的灯都关掉”
  • “显示传感器的温度”
  • “今天的温度历史是多少?”
  • “创建日落时自动开灯”
  • “当能耗超过700千瓦时发出警报”

🛠️ 可用工具

MCP服务器公开 8工具 与家庭助理交互:

📋 实体管理

  • get_entities :列出所有具有域筛选的实体
  • get_entity_state :获取实体的详细状态
  • get_history :给定时期的实体历史

🎮 设备控制

  • call_service :调用服务来控制设备
  • get_services :列出所有可用服务

🤖 自动化 新

  • create_automation :生成即用型YAML自动化
  • list_automations :列出所有活动的自动化
  • toggle_automation :启用/禁用自动化

💡 自动化示例

⚡ 能源监测

- alias: "High consumption alert"
  trigger:
    - platform: numeric_state
      entity_id: sensor.kws_306wf_energie_totale
      above: 700
  action:
    - service: persistent_notification.create
      data:
        title: "⚡ High Consumption"
        message: "More than 700 kWh consumed!"

🌅 自动照明

- alias: "Lights at sunset"
  trigger:
    - platform: sun
      event: sunset
      offset: "-00:30:00"
  action:
    - service: light.turn_on
      target:
        area_id: living_room

📅 预定通知

- alias: "Morning notification"
  trigger:
    - platform: time
      at: "08:00:00"
  action:
    - service: persistent_notification.create
      data:
        title: "🌅 Good Morning!"
        message: "Have a great day!"

📚 文档

🔧 发展

# Development installation
pip install -e ".[dev]"

# Run tests
python tests/test_mcp_tools.py

# Analyze your installation
python tests/analyze_smart_plugs.py
python -m pytest

# Start the server
homeassistant-mcp-server

许可证

麻省理工学院


法文版

强大的模型上下文协议(MCP)服务器,用于将Home Assistant与Claude Desktop等AI代理集成。

🇬🇧 英文版本

✨ 功能

  • 🏠 实体读取 :查看所有家庭助理设备的状态
  • 🎮 设备控制 :打开/关闭灯、开关等。
  • 📊 历史 :访问传感器和实体的历史记录
  • 🔐 安全认证 :使用Home Assistant访问令牌
  • 🚀 演出 :异步连接以实现最佳响应
  • 🛠️ 服务 :呼叫任何家庭助理服务
  • 🤖 自动化 :生成智能YAML自动化

🌐 HTTP服务器模式

除了MCP协议之外,该服务器还可以作为独立的HTTP REST API服务器运行,非常适合:

  • 🍓 Raspberry Pi部署 在家庭助理旁边
  • 🔗 应用程序web 以及自定义集成
  • 🚀 架构微服务
  • 📱 手机应用 和第三方工具
  • 🤖 IA代理商 不直接支持MCP协议

为什么使用HTTP服务器模式?

  • 通用兼容性 :任何语言或工具都可以通过HTTP连接
  • 直接部署 :使用Home Assistant直接安装在Raspberry Pi 3b+上
  • 客户MCP要求 :适用于任何HTTP客户端(curl、邮递员、浏览器)
  • 标准REST API :易于与现有系统和工作流集成
  • 自主操作 :不需要MCP基础设施的独立服务

📁 项目结构

homeassistant-mcp-server/
├── src/                              # Code source principal
│   └── homeassistant_mcp_server/
│       └── server.py                 # Serveur MCP principal
├── tests/                            # Scripts de test et analyse
│   ├── test_connection.py            # Test connexion de base
│   ├── test_mcp_tools.py             # Test complet des outils
│   ├── analyze_energy.py             # Analyse énergétique
│   └── analyze_smart_plugs.py        # Analyse prises connectées
├── examples/                         # Exemples et configuration
│   ├── claude_desktop_config.json    # Configuration Claude Desktop
│   └── smart_plug_automations.py     # Automatisations des prises
├── docs/                             # Documentation
│   ├── QUICKSTART.md                 # Guide de démarrage rapide
│   └── ARCHITECTURE.md               # Architecture technique
├── .env.example                      # Exemple de configuration
└── README.md                         # Ce fichier

🚀 安装

快速启动选项

🍓 安装Raspberry Pi(推荐)

使用Home Assistant直接安装在Raspberry Pi 3b+上:

curl -sSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash

🎯 针对Raspberry Pi 3b+进行了优化:

  • ✅ HTTP服务器配置 :安装独立的HTTP服务器,以便轻松进行AI集成
  • ✅ 配置交互 :在安装过程中请求令牌和URL Home Assistant
  • ✅ 服务体系d :自动配置系统服务以自动启动
  • ✅ 安全 :适当的文件权限和服务隔离
  • ✅ 端口3002 :可从外部机器访问的HTTP REST API
  • ✅ 优化资源 :适用于PI 3B+硬件的轻量级部署
  • ✅ 兼容Debian :在Raspberry Pi OS(基于Debian)上测试

系统要求:

  • 复盆子Pi 3b+或更高版本
  • Raspberry Pi OS(建议使用Debian 11+)
  • 在同一PI或网络上运行的家庭助理
  • Python 3.9+(必要时自动安装)
  • 至少512MB可用RAM

📖 指南完成Raspberry Pi

💻 安装局

对于远程开发或安装:

先决条件

  • Python 3.8+
  • 启用API的家庭助手
  • Home Assistant访问令牌

服务器安装

cd homeassistant-mcp-server
pip install -e .

配置

  1. 创建文件 .env :
HASS_URL=http://192.168.1.22:8123
HASS_TOKEN=votre_token_ici
  1. 获取您的家庭助理代币:
    • 转到主页助手>个人资料>长期访问令牌
    • 创建新令牌
    • 将其复制到文件中 .env

配置克劳德桌面

将此添加到您的Claude桌面配置(claude_desktop_config.json) :

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

📄 完整的配置文件可在 examples/claude_desktop_config.json

🤖 d'IA服务配置

克劳德桌面版

将此添加到您的Claude桌面配置(claude_desktop_config.json) :

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

LM工作室

在LM Studio中配置MCP:

  1. 打开LM Studio
  2. 转到设置>MCP服务器
  3. 添加新服务器:
    • 诺姆 : homeassistant
    • 命令 : homeassistant-mcp-server
    • 环境变量 :
      HASS_URL=http://192.168.1.22:8123
      HASS_TOKEN=votre_token_ici
      

Continue.dev(扩展VS代码)

添加到您的配置继续(.continue/config.json) :

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

光标IDE

添加到光标AI配置:

  1. 打开Cursor IDE
  2. 转到设置>IA>MCP服务器
  3. 添加服务器配置:
    {
      "name": "homeassistant",
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
    

Cline(扩展VS代码)

在Cline设置中配置:

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "args": [],
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

OpenWeb用户界面

对于OpenWebUI MCP集成:

  1. 安装MCP插件
  2. 在设置中配置服务器:
    servers:
      homeassistant:
        command: homeassistant-mcp-server
        env:
          HASS_URL: "http://192.168.1.22:8123"
          HASS_TOKEN: "votre_token_ici"
    

个性化集成

对于其他MCP兼容服务,请使用以下标准格式:

{
  "servers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

🔧 配置注释:

  • 替换 votre_token_ici 通过您真正的代币家庭助理
  • 如果您的家庭助理在其他地址工作,请更新URL
  • 某些服务可能需要可执行文件的完整路径
  • 添加配置后重新启动IA服务

🧪 测试与验证

使用提供的脚本测试安装:

# Test de connexion Home Assistant
python tests/test_connection.py

# Test complet de tous les outils MCP
python tests/test_mcp_tools.py

# Analyse de votre consommation énergétique
python tests/analyze_energy.py

# Analyse de vos prises connectées
python tests/analyze_smart_plugs.py

# Génération d'automatisations d'exemple
python examples/smart_plug_automations.py

💬 使用

配置后,您可以询问Claude:

  • “我的灯亮着吗?”
  • “关掉客厅里的所有灯”
  • “告诉我传感器的温度”
  • “我的温度传感器今天的历史是什么?”
  • “创建在日落时打开灯光的自动化”
  • “当我的能耗超过700 kWh时,生成警报”

🛠️ 可用工具

MCP服务器公开 8工具 要与家庭助理交互:

📋 实体管理

  • get_entities :按域筛选的所有实体列表
  • get_entity_state :获取实体的详细状态
  • get_history :给定时间段内实体的历史记录

🎮 设备控制

  • call_service :调用服务以控制设备
  • get_services :列出所有可用服务

🤖 自动化 (新风格!)

  • create_automation :生成现成的YAML自动化
  • list_automations :列出所有活动自动化
  • toggle_automation :启用/禁用自动化

💡 自动化示例

⚡ 能源监测

- alias: "Alerte consommation élevée"
  trigger:
    - platform: numeric_state
      entity_id: sensor.kws_306wf_energie_totale
      above: 700
  action:
    - service: persistent_notification.create
      data:
        title: "⚡ Consommation Élevée"
        message: "Plus de 700 kWh consommés !"

🌅 自动照明

- alias: "Lumières au coucher du soleil"
  trigger:
    - platform: sun
      event: sunset
      offset: "-00:30:00"
  action:
    - service: light.turn_on
      target:
        area_id: salon

📅 计划通知

- alias: "Notification matinale"
  trigger:
    - platform: time
      at: "08:00:00"
  action:
    - service: persistent_notification.create
      data:
        title: "🌅 Bonjour !"
        message: "Bonne journée !"

� 项目结构

McpHomeAssistant/
├── 📂 docs/                    # 📚 Documentation complète
│   ├── DEPLOYMENT_GUIDE.md     # Guide de déploiement
│   ├── PHASE_3_4_README.md     # Documentation Phase 3.4
│   ├── QUICK_INSTALL_RPI.md    # Installation rapide
│   └── ...                     # Autres guides
├── 📂 tests/                   # 🧪 Suite de tests
│   ├── test_simple.py          # Tests rapides
│   ├── test_complete.py        # Tests complets
│   ├── test_web_interface.py   # Tests interface web
│   └── ...                     # Autres tests
├── 📂 web/                     # 🌐 Interface Web Phase 3.4
│   ├── static/css/main.css     # Framework CSS responsive
│   ├── static/js/dashboard.js  # SPA JavaScript
│   └── templates/              # Templates HTML
├── 📂 src/                     # 📦 Code source principal
├── 📂 configs/                 # ⚙️ Configurations
├── 📂 examples/                # 💡 Exemples d'usage
├── 🚀 install.sh               # Script installation unifié
├── 🏠 bridge_server.py         # Serveur principal
├── 🖥️ start_server.py          # Script de démarrage
└── 📋 README.md                # Ce fichier

�📚 文档

🚀 安装和部署

🏗️ 建筑与发展

🧪 测试与验证

🔧 发展

# Installation en mode développement
pip install -e ".[dev]"

# Exécuter les tests
python tests/test_mcp_tools.py

# Analyser votre installation
python tests/analyze_smart_plugs.py
python -m pytest

# Lancement du serveur
homeassistant-mcp-server

许可证

麻省理工学院