使用说明

MCP家庭助理辅助

一个家庭助理对话代理，使用MCP（模型上下文协议）进行高效的实体发现，实现 代币减少95% 与传统方法相比。与LM Studio、llama.cpp、Ollama、OpenAI、Google Gemini、Anthropic Claude和OpenRouter合作。

主要特点

✅ 代币减少95%：使用MCP工具进行动态实体发现，而不是发送所有实体
✅ 无实体转储：从不向LLM发送12000多个令牌实体列表
✅ 智能实体索引：用于上下文感知查询的预生成系统结构索引（~400-800个标记）
✅ 多平台支持：与LM Studio、llama.cpp、Ollama、OpenAI、Google Gemini、Anthropic Claude和OpenRouter合作
✅ 多语言支持：21种语言，具有本地化的UI、系统提示和语音检测
✅ 多回合对话：维护对话上下文和历史记录
✅ 动态发现：按区域、类型、设备类、状态或名称按需查找实体
✅ 网络搜索工具：可选DuckDuckGo或Brave Search集成以获取当前信息
✅ 与1000+实体合作：即使安装了大型家庭助理，也很高效
✅ 多配置文件支持：运行多个具有不同模型的对话代理

MCP辅助解决的问题

传统语音助手发送您的 整个实体列表 （灯、开关、传感器等）在每次请求时都会发送到LLM。对于一个拥有200多台设备的典型家庭来说，这意味着：

12000+代币 每次发送
昂贵的API成本（云LLM）
响应缓慢
上下文窗口限制
大型住宅的性能不佳

MCP Assist的工作原理

MCP Assist没有倾倒所有实体，而是：

启动MCP服务器 在公开实体发现工具的Home Assistant上
您的LLM连接 访问MCP服务器并访问这些工具：
- get_index -获取系统结构索引（区域、域、设备类、人员等）
- discover_entities -按类型、区域、域、设备类或状态查找实体
- get_entity_details -获取当前状态和属性
- perform_action -控制装置
- run_script -执行脚本并返回响应数据
- run_automation -手动触发自动
- list_areas -列出家中的所有区域
- list_domains -列出所有实体类型
- set_conversation_state -智能跟进处理
LLM使用索引进行智能查询 -了解在没有完整上下文转储的情况下存在什么
LLM按需发现 -只获取每个请求所需的实体
代币使用量下降 每次请求从12000+到~400个令牌

令牌使用情况比较

方法	令牌使用	描述
传统	12000+令牌	发送所有实体状态
MCP辅助	约400个令牌	使用MCP工具进行发现
减少	95%	大幅提高效率

智能实体指数（v0.5.0+）

智能实体索引提供了家庭助理系统结构的轻量级（约400-800个令牌）快照，支持上下文感知查询，而无需完整的实体转储。该索引包括区域、域、设备类、人员、日历、区域、自动化和脚本。对于没有标准化device_class属性的实体（如自定义集成），LLM支持的间隙填充会自动从命名模式中推断语义类别。这导致更快、更准确的查询，与传统的实体转储相比，使用的令牌减少了约95%。

多语言支持（v0.12.0+）

MCP辅助支持 21种语言 具有本地化的配置界面、语言感知系统提示和特定区域的语音检测模式。该集成会自动检测您的家庭助理系统语言，并为系统提示、后续短语和结束对话单词提供适当的默认值。支持的语言包括：阿拉伯语、中文（简体）、捷克语、丹麦语、荷兰语、芬兰语、菲律宾语、法语、德语、希腊语、印地语、意大利语、日语、韩语、挪威语、波兰语、葡萄牙语、俄语、西班牙语、瑞典语和土耳其语。

需求

家庭助理2024.1+
什么之中的一个：
- 本地LLMs：lm Studio v0.3.17+，calla.cpp或ollama
- 云LLMs：OpenAI、Google Gemini、Anthropic Claude或OpenRouter（需要API密钥）
Python 3.11+

安装

添加到HACS

选项A:HACS（推荐）

单击上面的徽章将此存储库添加到HACS，或手动将其添加为自定义存储库
从HACS安装“MCP辅助”
重新启动家庭助理

选项B：手动安装

复制 custom_components/mcp_assist 文件夹到您的家庭助理 custom_components 目录
重新启动家庭助理

配置

1.添加集成

首选设置 → 设备和服务 → 添加集成
搜索“MCP Assist”并选择它

2.设置流程

步骤1-配置文件和服务器类型：

个人资料名称：给你的助理起个名字（例如“客厅助理”）
服务器类型：选择您的LLM提供商
- LM工作室 -本地、免费、在您的机器上运行
- llama.cpp -本地免费官方llama.cpp服务器
- 奥拉玛 -本地、免费、基于命令行
- 开放人工智能 -云、付费、GPT-5.2系列
- 谷歌双子座 -云，付费/免费层，Gemini 3.0系列
- 开放路由 -云，多模型网关，可访问200多种模型

步骤2-服务器配置：

对于本地服务器（LM工作室/lama.cp/Ollama）：

服务器URL：LLM服务器运行的位置
- LM工作室： http://localhost:1234 （默认）
- llama.cpp： http://localhost:8080 （默认）
- 奥拉马： http://localhost:11434 （默认）
MCP服务器端口：MCP服务器的端口（默认值：8090）

对于云提供商（OpenAI/Gemini/Autopic/OpenRouter）：

API密钥：您的提供商API密钥（有关设置，请参阅下文）
MCP服务器端口：MCP服务器的端口（默认值：8090）

第3步-模型和提示：

型号名称：从自动加载的型号中选择或手动输入
系统提示：自定义助手的个性
技术说明：工具使用高级提示（预配置）

步骤4-高级设置：

温度：响应随机性（0.0-1.0）
最大响应令牌数：响应的最大长度
响应模式：无/智能/始终（对话继续行为）
后续短语：用于模式检测的可配置短语（默认：“还有什么，你愿意吗，我可以吗”等）
结束对话单词：结束对话的单词/短语（默认：“再见，谢谢，停止”等）
控制主页助手：启用/禁用设备控制
最大工具迭代次数：每个请求允许多少次工具调用
网络搜索提供商：选择无、DuckDuckGo或Brave搜索
勇敢搜索API密钥：您的API密钥（如果使用勇敢搜索）
调试模式：用于故障排除的额外日志记录
Ollama 保持活跃 （仅限Olama）：控制模型在内存中加载的时间
- -1 =无限期保持加载状态
- 0 =响应后立即卸载
- "5m" =保持5分钟（默认）
- 持续时间字符串，如 "24h", "168h" 也支持
Ollama上下文窗口 （仅限Ollama）：自定义上下文窗口大小（0=使用模型默认值）

3.设置为语音助手

在Home Assistant中，转到设置 → 语音助理
将您的首选助手设置为您的MCP Assist配置文件名称
用命令测试！

用法示例

基本命令

“打开厨房的灯”
“把卧室里的灯都关掉”
“客厅的温度是多少？”

多回合对话

用户“什么灯亮着？”
助手：“厨房和客厅的灯都亮着。”
用户：“关掉厨房一号”
助手“我把厨房的灯关掉了。”

复杂查询示例

用户：“我们有泄漏吗？”

幕后：

1. LLM calls get_index → Sees moisture sensors and water flow monitors exist in system
2. LLM calls discover_entities(device_class="moisture")
   → Returns: binary_sensor.bathroom_leak, binary_sensor.kitchen_sink_leak, binary_sensor.laundry_leak
3. LLM calls discover_entities(name_contains="water flow")
   → Returns: sensor.water_flow_rate
4. LLM calls get_entity_details for each sensor
   → bathroom leak: "off", kitchen leak: "off", laundry leak: "on", water flow: "2.5 gpm"
5. LLM synthesizes response

助手“是的，洗衣房的漏水传感器正在检测水，水以每分钟2.5加仑的速度流动。浴室和厨房的传感器都是干的。”

后续用户：“关闭总水管”

幕后：

1. LLM calls discover_entities(name_contains="water main")
   → Returns: switch.water_main_shutoff
2. LLM calls perform_action(entity_id="switch.water_main_shutoff", action="turn_off")
   → Success

助手：“我已经关闭了主水阀。”

网络搜索（如果启用）

“明天的天气预报是什么？”
“搜索最新的家庭助理更新”
“商店几点关门？”

配置选项

个人资料设置

个人资料名称：此助理的唯一名称
服务器类型：LM工作室，Ollama（更多即将推出）
服务器URL：你的法学硕士在哪里
型号名称：使用哪种型号

提示

系统提示：设置助理的个性和行为
技术说明：工具使用的低级说明（通常保留为默认值）

高级设置

最大响应令牌数：限制响应长度（默认值：500）
最大历史消息数：要记住多少次对话（默认值：10）
最大工具迭代次数：防止无限循环（默认值：10）
响应模式:
- 无：永远不要要求跟进，立即结束
- 聪明的 （默认）：相关的上下文跟进，用户可以以“再见”/“谢谢”结束
- 总是：自然的对话跟进，用户可以以“再见”/“谢谢”结束
后续短语：逗号分隔的短语，用于检测助手何时想要继续（可根据配置文件配置）
结束对话单词：逗号分隔的单词/短语用于用户发起的结尾（可根据配置文件配置）
启用智能实体索引：上下文感知实体发现，为不常见的设备自动填充间隙（默认：启用）

温度设置

温度控制响应随机性（0.0=确定性，1.0=创造性）。不同的提供商具有不同的最优值：

提供者	默认值	原因
双子座	`1.0`	谷歌要求Gemini 3版本为1.0，以避免“循环或性能下降”
OpenAI（GPT-4）	`0.5`	平衡可靠的工具调用
OpenAI（GPT-5/o1）	N/A	推理模型不使用温度
Anthropic Claude	`0.5`	在0.5-1.0范围内工作良好
LM工作室/lama.cpp	`0.5`	较低的温度提高了刀具调用的准确性
奥拉玛	`0.5`	取决于型号，工具越低越安全
开放路由	`0.5`	取决于基础模型

备注：您始终可以在“高级设置”中覆盖这些默认值。对于家庭助理语音控制，较低的温度（0.5-0.7）通常可以提供更一致的工具调用和准确的实体控制。

MCP服务器设置

MCP服务器端口：默认8090（端口冲突时更改）
其他允许的IP/范围：将Docker容器列入白名单（例如。， 172.30.0.0/16)或用于外部MCP客户端的特定IP，如Claude Code插件

网络搜索

Web搜索提供商：从以下选项中选择：
- 无：搜索已禁用
- DuckDuckGo：免费网络搜索（不需要API密钥）
- 勇敢的搜索：需要来自的API密钥https://brave.com/search/api/
勇敢搜索API密钥：仅在使用Brave Search时才需要

共享与按配置文件设置

MCP辅助有两种设置：

每个配置文件设置 （每个对话代理独立）：

型号名称、系统提示、技术说明
温度、最大令牌、响应模式
调试模式，最大迭代次数
服务器URL（用于本地LLM）

共享设置 （影响所有配置文件）：

MCP服务器端口
网络搜索提供商（无/鸭子/勇敢）
勇敢的API密钥
允许的IPs/CIDR范围
智能实体指数（填补空白）

当您更改一个配置文件选项中的共享设置时，它们将应用于所有配置文件。这是有意的，因为所有配置文件共享同一个MCP服务器。

型号兼容性指南

并非所有LLM模型都同样支持工具调用（函数调用）。 这种集成最适合前沿模型 （GPT-5.2，克劳德作品4.5，双子座3闪光） 或更高规格的本地型号较小的模型可能难以处理需要合成大型工具结果集的复杂多实体查询。

了解工具调用要求

工具调用（函数调用）要求模型：

了解用户的请求
决定调用哪个工具
将工具参数正确格式化为JSON
解释工具结果
产生自然反应

影响工具调用成功的因素:

模型尺寸：较大的型号（8B+）通常能更好地处理刀具调用
模型架构：视觉语言（VL）模型的行为与标准模型不同
推理机：LM Studio和Ollama以不同的方式优化模型
量化电平：Q4与Q8会影响指令遵循

指导与思维/推理模型

指导模型 （例如。， qwen3-8b-instruct):

快速响应时间
最适合简单的单次操作请求（“打开厨房灯”）
可能难以处理需要多次工具调用的复杂查询
适用于基本语音命令

思维/推理模型 （例如。， qwen3-8b-thinking):

较慢的响应时间（更深思熟虑的推理）
更擅长处理复杂的请求 需要多个工具调用和上下文
可靠地处理多步骤查询（“检查所有房间是否有打开的窗户，然后关闭这些房间的灯”）
推荐给家庭助理 其中查询通常涉及发现+操作组合

选择最适合您用例的模型类型。思维/推理模型为复杂的多工具查询提供了更好的可靠性，而指令模型为简单命令提供了更快的响应。

测试您的模型

调用工具时 不起作用，您将看到：

模特声称“我开灯了”，但什么都没发生
不 perform_action 日志中的工具调用
动作不执行，只有叙述

调用工具时 工作正常，您将在日志中看到：

discover_entities 呼叫查找设备
perform_action 被召唤去控制它们
"✅ 成功执行“消息
设备实际更改状态
工具调用在设置中可见→ 语音助理→ （个人资料）→ Debug

通用指南

从较大的型号开始 （30B）如果你的硬件支持它，它们可以跨平台一致地工作。

如果使用较小的型号 （4B-8B），彻底测试：

尝试一个简单的命令，比如“打开厨房的灯”
检查日志以验证是否正在调用工具
确认设备实际改变状态
如果不起作用，请在不同的平台上尝试相同的模型（LM Studio vs Ollama）

视觉语言（VL）模型 针对多模式任务进行了优化，并且可能具有与标准模型不同的工具调用行为。

动态模型切换

MCP Assist的功能之一是 动态模型切换 -您可以在配置UI中更改模型，并且无需重新启动Home Assistant即可立即生效。这使得以下操作变得容易：

测试不同型号
在快速（Q4）和高质量（Q8）量化之间切换
试用发布的新型号

故障排除

集成无法启动

检查MCP端口是否尚未使用
验证家庭助理是否有权绑定到端口
检查家庭助理日志中的特定错误消息

LM Studio无法连接到MCP

确保MCP服务器正在运行（检查集成状态）
验证LM Studio中的MCP配置是否正确
检查LM Studio中的URL是否与您的MCP端口匹配（默认值：8090）
更改MCP配置后重新启动LM Studio

Ollama连接问题

确认Ollama正在运行： ollama list
检查Ollama运行的URL是否匹配（默认值： http://localhost:11434)
确保模型已加载到Olama中

云提供商连接问题

向您的提供商验证您的API密钥是否有效
检查您是否还有足够的学分/配额
检查Home Assistant日志中的速率限制错误
如果身份验证失败，请尝试重新生成API密钥
验证您的互联网连接是否正常工作
检查Home Assistant日志以获取特定错误代码

助理没有回应

验证您的LLM是否加载了模型
检查集成中的模型名称是否完全匹配
确保您的实体暴露在对话助手中
查看Home Assistant日志以了解API错误
启用调试模式以进行更详细的日志记录

响应质量差

尝试不同/更大的型号
调整温度设置（较低=更专注）
确保模型支持工具调用/函数调用
检查技术说明是否未被修改

工具不工作

验证“Control Home Assistant”是否已启用
检查实体是否已公开（设置→ 语音助理→ 暴露）
在日志中查找MCP服务器错误
确保“最大工具迭代次数”设置得不太低

实体风险敞口

集成仅发现暴露于“对话”助手的实体。要公开实体，请执行以下操作：

首选设置 → 语音助理 → 暴露
选择您希望助手控制的实体
集成将在需要时自动发现这些

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

问题: GitHub问题
讨论: GitHub讨论
家庭助理社区: 社区论坛