快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

pip install copier

详细介绍

家庭助理集成模板

A. 复印机用于引导Home Assistant与完全配置的开发环境进行自定义集成的模板。

所得

Devcontainer：Python 3.14、uv、gh-CLI、Ruff、Pylance——在VS Code/Coursor中打开并正常工作
CI工作流：Ruff-lint、Hassfest、HACS验证、CodeQL、自动发布
预提交挂钩：每次提交时都使用Ruff格式+lint
Dependabot：自动更新GitHub操作版本
一体化脚手架: manifest.json，配置流，常量，字符串，翻译
试验脚手架：pytest+pytest-homeassistant自定义组件
MCP开发服务器：HA生命周期工具（重启、日志、状态、服务）+MQTT工具，具有自动发现功能，可添加特定于集成的工具
脚本: scripts/setup （安装deps）和 scripts/develop （在本地运行HA）

快速开始

创建新集成

# Install copier (one time)
pip install copier

# Scaffold a new integration
copier copy gh:eyalmichon/ha-integration-template ./ha-my-integration

系统将提示您输入下面描述的选项。

更新现有集成

改进此模板时，将更改拉入现有集成：

cd ha-my-integration
copier update

Copier显示模板更改和本地修改之间的差异，让您像git一样合并。

模板选项参考

`domain`

集成域标识符。用作下的文件夹名称 custom_components/，the DOMAIN 并且在所有面向HA的标识符中。

类型：string
示例: my_device, smart_thermostat, solar_monitor
规则：仅限小写字母、数字和下划线。必须以字母开头。

`integration_name`

HA UI、README、HACS列表和配置流中显示的人类可读名称。

类型：string
示例: My Device, Smart Thermostat, Solar Monitor

`description`

对集成功能的简短描述。在生成的README和HACS元数据中使用。

类型：string
默认: A custom Home Assistant integration
示例: Monitor and control your Smart Thermostat from Home Assistant

`github_user`

您的GitHub用户名。用于生成URL（文档、问题跟踪器）、代码所有者和徽章链接。

类型：string
示例: eyalmichon
生成: https://github.com//ha-

`git_name`

devcontainer中提交的Git作者名称。在项目级别配置 .git/config 通过 scripts/setup.

类型：string
示例: Eyal Michon

`git_email`

Git作者在devcontainer中提交的电子邮件。在项目级别配置 .git/config 通过 scripts/setup.

类型：string
示例: eyal@example.com

`iot_class`

集成如何连接到设备/服务。这是在 manifest.json 并在HA集成页面中显示。请参阅 HA关于IoT类的文档了解详情。

类型：选择
默认: local_polling
选项:

值	何时使用
`local_polling`	定期轮询本地设备/服务
`local_push`	本地设备/服务推送更新（例如通过MQTT、webhooks）
`cloud_polling`	定期轮询云API
`cloud_push`	云服务推送更新（例如通过websocket）
`calculated`	实体值是根据其他数据计算的，没有外部I/O
`assumed_state`	根据最后发送的命令假设状态（无反馈）

`integration_type`

这种集成会影响HA如何处理配置条目。请参阅 HA关于集成类型的文档.

类型：选择
默认: service
选项:

值	何时使用
`hub`	连接到管理多个设备（如Hue、Z-Wave）的集线器/网桥
`device`	直接表示单个设备（例如智能插头）
`service`	连接到非物理设备的服务/API（例如天气、日历）

`platforms`

您的集成将公开的HA平台的逗号分隔列表。每个平台都成为 PLATFORMS 列入 const.py.

类型：string（逗号分隔）
默认: sensor
示例: sensor,switch,binary_sensor
可用平台:

平台	实体类型
`sensor`	数字/文本读数（温度、能量、计数）
`binary_sensor`	开/关状态（运动、门打开、连接）
`switch`	可切换的开/关控制
`button`	一键触发（重启、同步）
`select`	从选项列表中下拉选择
`number`	带最小/最大/步长的数字输入
`climate`	暖通空调/恒温器控制
`light`	灯光控制（亮度、颜色）
`cover`	百叶窗、车库门、百叶窗
`fan`	风扇速度/方向控制
`lock`	锁定/解锁控制
`media_player`	媒体播放控制
`camera`	相机流/快照

`has_config_flow`

是否包含配置流（设置>设备和服务中的基于UI的设置向导）。几乎总是 true 用于新的集成。

类型：boolean
默认: true

`python_version`

devcontainer的Python版本 pyproject.toml。应与您的目标家庭助理版本所需的版本相匹配。家庭助理2026.3+需要Python 3.14+；较旧的HA版本仍然支持Python 3.13。

类型：string
默认: 3.14

`install_hacs`

是否安装计算机危险判定系统（家庭助理社区商店）在开发环境中。将下载和依赖项安装添加到开发脚本中。本地开发您自己的集成时不需要，但如果您想与其他自定义集成一起测试，则很有用。

类型：boolean
默认: false

`dev_integrations`

可选的额外HA集成可包含在开发中 configuration.yaml基本配置已经包含了所有轻量级的内置集成（自动化、脚本、场景、输入助手、模板、记录器、历史记录、日志、sun等）。这些是您可以选择的更重或更专业的集成。

类型：多选
默认：无

选择	价值
MQTT代理（本地蚊子）	`mqtt`
REST命令/传感器	`rest`
移动应用支持	`mobile_app`
能源仪表板	`energy`
媒体来源	`media_source`

生成的项目结构

ha-my-integration/
  .devcontainer/devcontainer.json     # Dev environment config
  .github/
    workflows/                        # CI: lint, hassfest, HACS, release, CodeQL
    dependabot.yml                    # Auto-update GH Actions
  .cursor/mcp.json                    # MCP server config
  .pre-commit-config.yaml             # Ruff hooks
  custom_components/my_device/        # Integration code
    __init__.py                       # Setup/unload entry
    config_flow.py                    # Config flow
    const.py                          # Domain + platforms
    manifest.json                     # HA manifest
    strings.json                      # UI strings
    translations/en.json              # English translations
    brand/                            # Local icon/logo for HA 2026.3+
  scripts/
    setup                             # Install deps + pre-commit
    develop                           # Run HA locally
    mcp_server/                       # Dev MCP tools
      tools/ha.py                     # HA lifecycle tools
      tools/mqtt.py                   # MQTT tools
  tests/
    conftest.py                       # Test fixtures
  pyproject.toml                      # Python config
  hacs.json                           # HACS metadata

开发此模板

当对模板本身进行更改时，您可以使用以下命令在本地进行测试，而无需提交或推送 --vcs-ref=HEAD。此操作会通知复印机使用最新提交加上任何脏的（未提交的）更改，绕过基于标记的版本解析：

# Test with defaults
copier copy --trust --vcs-ref=HEAD --defaults \
  -d domain=test_integration \
  -d integration_name="Test Integration" \
  -d git_name="Test User" \
  -d git_email="test@example.com" \
  ./path/to/ha-integration-template /tmp/test-scaffold

# Test with multiselect options via a data file (workaround for -d multiselect bug)
cat > /tmp/copier-data.yml  **备注**：没有 `--vcs-ref=HEAD`，复印机解析最新的git标签并读取 `copier.yml` 来自该标签——因此，在标记之前，新的问题或模板更改不会出现。这 `--data-file` 多选题需要这种方法，因为 `-d` 旗有 [已知复印机故障](https://github.com/copier-org/copier/issues/1594) 具有多选值。

## 添加集成专用MCP工具

MCP服务器自动发现工具模块。在中添加新文件 `scripts/mcp_server/tools/`:

scripts/mcp_server/tools/my_device.py

from typing import Any

def register(mcp) -> None: @mcp.tool async def my_device_status() -> dict[str, Any]: """Check My Device status.""" return {"status": "ok"}


它将被自动提取，无需导入或注册。

目录标签

Cursor智能家居AI代理Jinja本地部署HomeAssistant集成开发自动化工具模板工具

支持客户端

CursorVS Code

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

none

工具数量（toolCount，工具数）

0

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdionone部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/3fcbf8525e5f67211185c047cf15a94f

一个用于快速启动Home Assistant自定义集成的Copier模板，提供完整的开发环境配置。

继续浏览同类 MCP

更多AI代理 MCP（18,706）返回 MCP 目录

上一个 MCP

Hahooh MCP

MCP流式HTTP代理服务，用于桥接基于STDIO的MCP客户端与流式HTTP的MCP服务器，支持完整的MCP协议功能。

下一个 MCP

Haksnbot Memory

一个基于SQLite的MCP服务器，为AI代理提供持久化内存存储和全文搜索功能。

Ha Integration Template

快速接入

详细介绍

家庭助理集成模板

所得

快速开始

创建新集成

更新现有集成

模板选项参考

domain

integration_name

description

github_user

git_name

git_email

iot_class

integration_type

platforms

has_config_flow

python_version

install_hacs

dev_integrations