ha-mcp: điều khiển Home Assistant bằng Claude, ChatGPT — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
ha-mcp là một MCP server nguồn mở (giấy phép MIT) giúp các trợ lý AI như Claude, ChatGPT đọc và cấu hình Home Assistant thay bạn. Bạn chỉ cần nói bằng lời thường: tạo automation, thêm thẻ dashboard, xem vì sao một automation không chạy. Cách cài khuyên dùng là tích hợp qua HACS hoặc Marketplace, thao tác chủ yếu bằng giao diện Home Assistant nên không quá khó.
ha-mcp là một MCP server cho Home Assistant. Nói đơn giản: nó là cầu nối để các trợ lý AI như Claude, ChatGPT (và nhiều ứng dụng khác hỗ trợ MCP) nhìn thấy nhà thông minh của bạn, rồi đọc, sửa và điều khiển nó theo yêu cầu bằng lời thường.
Nếu bạn đang dùng Home Assistant, chắc bạn biết cảnh này: muốn tạo một automation đơn giản mà phải mò YAML, mò giao diện, sai một dấu cách là hỏng. Với ha-mcp, bạn gõ "tạo automation bật đèn hiên lúc mặt trời lặn" và AI làm phần cấu hình giúp. Repo này hợp với người đã có Home Assistant và muốn bớt thời gian cấu hình, từ người chơi nhà thông minh nghiệp dư đến dev muốn quản lý nhiều thứ nhanh hơn.
Điểm đáng giá nhất là cách cài: repo khuyên cài thành một tích hợp ngay trong Home Assistant (qua HACS hoặc Marketplace), chạy được trên mọi kiểu cài đặt Home Assistant, và có sẵn bảng cài đặt, chế độ chỉ đọc, sao lưu tự động trước khi sửa. Hiện repo có khoảng 7720 sao và 468 fork, vẫn được cập nhật trong 3 tháng gần đây.
homeassistant-ai/ha-mcp
ha-mcp là MCP server cho Home Assistant: nói chuyện với Claude hay ChatGPT để tạo automation, sửa dashboard, gỡ lỗi và điều khiển thiết bị trong nhà.
I.ha-mcp làm được gì
Ảnh tổng quan: AI nhận được một bộ "công cụ" để làm việc với Home Assistant. Theo README, các nhóm chính là:
- Tìm kiếm. Tìm thực thể theo kiểu gần đúng (fuzzy), tìm sâu trong cấu hình, xem tổng quan hệ thống. Bạn không cần nhớ chính xác tên thiết bị, chỉ cần nói gần giống.
- Điều khiển. Gọi bất kỳ dịch vụ nào, điều khiển hàng loạt thiết bị, xem trạng thái thời gian thực. Tiện khi muốn tắt cả loạt đèn một lúc.
- Quản lý. Automation, script, helper, dashboard, khu vực (areas), vùng (zones), nhóm, lịch, blueprint. Đây là phần tiết kiệm công nhất vì thay vì sửa tay từng file, bạn nhờ AI sửa.
- Giám sát. Lịch sử, thống kê, ảnh chụp camera, dấu vết chạy (trace) của automation, thiết bị ZHA. Hữu ích khi gỡ lỗi "sao automation này không chạy".
- Hệ thống. Sao lưu/khôi phục, cập nhật, quản lý app (add-on), sổ đăng ký thiết bị.
- An toàn. Có công tắc Read Only Mode (chỉ đọc), bật/tắt từng công cụ, chính sách bảo mật cho từng công cụ (người dùng phải duyệt), và tự động sao lưu khi sửa.
Ngoài ra, khi cài theo cách khuyên dùng, trên thanh bên của Home Assistant xuất hiện một bảng HA-MCP dành cho admin để quản lý công cụ, cờ tính năng, bản sao lưu và giao diện.
II.Cần chuẩn bị gì
Tùy cách cài, bạn cần khác nhau. Với cách khuyên dùng (tích hợp HA-MCP):
- Một hệ thống Home Assistant 2026.8.0 trở lên. README nói cách này chạy trên mọi kiểu cài: Home Assistant OS, Supervised, Container và Core.
- HACS (với Home Assistant 2026.8 đến 2026.10) hoặc Marketplace có sẵn (từ Home Assistant 2026.11).
- Một tài khoản quản trị (administrator) để server hoạt động dưới danh nghĩa đó: hoặc token truy cập dài hạn trên tài khoản của bạn, hoặc (an toàn hơn) một tài khoản riêng chỉ dùng cho HA-MCP.
- Một ứng dụng AI hỗ trợ MCP, ví dụ Claude Desktop hay Claude Code. README nói Setup Wizard tạo cấu hình cho hơn 15 ứng dụng như Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor.
Nếu chạy ngoài Home Assistant bằng PyPI/uvx, pyproject.toml yêu cầu Python từ 3.14 trở lên (dưới 3.15). Để thử bản demo thì README ghi là không cần đăng ký trả phí. Riêng Claude Code trên Linux cần gói Claude trả phí. README chưa nói gì về yêu cầu phần cứng như GPU.
Server hoạt động bằng quyền của một tài khoản quản trị Home Assistant. Hãy coi token và URL kết nối như mật khẩu: không đăng lên mạng, không gửi vào nhóm chat.
III.Cài đặt từng bước
Dưới đây là cách cài khuyên dùng: tích hợp HA-MCP ngay trong Home Assistant. Toàn bộ thao tác làm trên giao diện web, không cần gõ lệnh.
- Cài tích hợpTìm HA-MCP trong HACS hoặc Marketplace rồi cài
- Khởi động lạiRestart Home Assistant
- Chọn tài khoảnTạo token hoặc tài khoản riêng cho HA-MCP
- Thêm tích hợpAdd Integration, chọn HA-MCP Server, nhập token và cách kết nối
- Lấy URLCopy URL kết nối ở màn hình Configure
- Dán vào AIDán URL vào ứng dụng AI của bạn
A.Cài tích hợp từ HACS hoặc Marketplace
Nếu Home Assistant của bạn là bản 2026.8 đến 2026.10, mở HACS, tìm HA-MCP, bấm Download. Nếu là bản 2026.11 trở lên, vào Settings → Marketplace, chấp nhận cảnh báo lần đầu, tìm HA-MCP, bấm Install. README nói HA-MCP nằm trong danh mục mặc định nên không cần kết nối GitHub hay thêm repo tùy chỉnh.
Bạn đã cài từ repo cũ homeassistant-ai/ha-mcp-integration? README nói nó vẫn nhận cùng các bản phát hành. Một số bản cài cũ còn hiện tên HA-MCP Custom Component, tìm "HA-MCP" vẫn ra cả hai.
Không dùng HACS hay Marketplace? Có cách cài thủ công: chép thư mục custom_components/ha_mcp_tools/ trong repo vào thư mục config/custom_components/ của Home Assistant, rồi restart và thêm tích hợp như các bước dưới.
B.Khởi động lại Home Assistant
Bước này hay bị quên. Sau khi cài xong, bạn phải restart Home Assistant thì tích hợp mới xuất hiện trong danh sách để thêm.
C.Chọn tài khoản cho server
Có hai cách. Cách một: tạo token truy cập dài hạn trên tài khoản của bạn (hồ sơ cá nhân → Security → Long-lived access tokens → Create token). README cảnh báo token này dùng được từ bất kỳ đâu nếu bị lộ, và các thay đổi của server sẽ hiện dưới tên bạn.
Cách hai, an toàn hơn: vào Settings → People → Add person, tạo một tài khoản riêng chỉ cho HA-MCP, bật Allow login, Local access only và Administrator. README dặn rõ: với cách này, đừng dùng tài khoản đăng nhập của chính bạn.
D.Thêm tích hợp
Vào Settings → Devices & Services → Add Integration, tìm HA-MCP và chọn HA-MCP Server. Dán token của bạn, hoặc nhập tên đăng nhập và mật khẩu của tài khoản riêng (HA-MCP sẽ tự tạo token). Sau đó chọn cách để ứng dụng AI kết nối:
- Remote access through Home Assistantnên bắt đầu với Secret URL cho đơn giản; Home Assistant sign-in thêm bước đăng nhập.
- Network access: Local networkcho thiết bị trong cùng mạng.
Cả hai mặc định đều tắt. Vì vậy nếu AI chạy trên thiết bị khác, bạn phải bật ít nhất một. Rồi bấm Submit.
E.Lấy URL kết nối
Mở màn hình Configure của mục này: Settings → Devices & Services → "HA-MCP — Manage Home Assistant with AI" → HA-MCP Server → Configure. Một thông báo cũng cho bạn biết server đã chạy và chỉ chỗ này. URL có dạng:
https://<your-ha-domain>/api/webhook/<webhook-id>Trong mạng nội bộ thì là http://<ha-host>:8123/api/webhook/<webhook-id>. Với máy cùng mạng, server cũng truy cập trực tiếp được ở:
http://<ha-ip>:9584/private_<random>F.Dán URL vào ứng dụng AI
Dán URL vào ứng dụng AI của bạn là xong. Cách khai báo MCP khác nhau theo từng ứng dụng, nên README gợi ý dùng Setup Wizard trên trang của dự án (https://homeassistant-ai.github.io/ha-mcp/setup/) để lấy đúng cấu hình cho ứng dụng bạn dùng.
Chỉ chọn MỘT cách cài cho mỗi ứng dụng AI. Nếu để hai mục cho cùng một server (ví dụ vừa có mục uvx chạy cục bộ, vừa có URL của tích hợp), README nói đây là nguyên nhân quen thuộc gây treo kết nối. Cũng đừng chạy tích hợp cùng lúc với một cách cài khác.
G.Các cách cài khác
Nếu bạn thích cách khác, README liệt kê:
- App (add-on) của Home Assistant (Home Assistant OS và Supervised): thêm repo
https://github.com/homeassistant-ai/ha-mcptrong Settings → Apps → Install app → ⋮ → Repositories, cài "Home Assistant MCP Server", bấm Start, rồi xem tab Logs để lấy URL MCP. Cách này không cần token. - Docker: chạy image
ghcr.io/homeassistant-ai/ha-mcpở chế độ HTTP, cần địa chỉ Home Assistant và token dài hạn. README chưa ghi lệnh đầy đủ ngay trong phần này, bạn xem trong Setup Wizard. Repo cũng cóDockerfilevàdocker-compose.yml. - PyPI / uvx: chạy gói
ha-mcpbằng lệnh sau, cũng ở chế độ HTTP:
uvx --python 3.14 ha-mcp@latest- stdio cục bộ: README không khuyến nghị vì có vấn đề kết nối, chỉ nên dùng để thử.
Các cách này dành cho người dùng Home Assistant Container hoặc Core (không chạy được app) hoặc muốn chạy server trên máy khác.
IV.Kiểm tra đã chạy được chưa
Với cách khuyên dùng, dấu hiệu đầu tiên là Home Assistant hiện thông báo server đã khởi động, và trên thanh bên có bảng HA-MCP (chỉ admin thấy). Màn hình Configure hiển thị URL kết nối.
Sau khi dán URL vào ứng dụng AI, hãy hỏi đúng câu mà README dùng để thử:
Can you see my Home Assistant?Bạn có thể hỏi bằng tiếng Việt, ví dụ "Bạn có thấy Home Assistant của mình không?". Nếu AI trả lời nhìn thấy hệ thống và liệt kê được thiết bị, vậy là thành công. Với Claude Code, README bảo chạy /mcp để xác nhận server đã được kết nối.
Muốn thử trước khi đụng vào nhà thật? README có script cài nhanh kết nối tới một môi trường demo. Trên Windows, mở PowerShell và chạy:
irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iexTrên macOS, mở Terminal:
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | shSau đó tải Claude Desktop (hoặc khởi động lại nó) và hỏi câu trên. Đây là cách xem repo hoạt động ra sao trong vài phút, không cần Home Assistant của bạn. Lưu ý các script này dùng kết nối stdio tới môi trường demo.
V.Dùng vào việc thật
Dưới đây là các tình huống bám theo ví dụ trong README. Bạn cứ nói tự nhiên với AI.
A.Chủ nhà muốn tạo automation mà không biết YAML
Chị Lan mới lắp đèn hiên thông minh, muốn nó tự bật khi trời tối nhưng chưa từng viết automation. Chị nói với Claude:
Create an automation that turns on the porch light at sunsetBạn có thể viết bằng tiếng Việt: "Tạo automation bật đèn hiên lúc mặt trời lặn". Theo README, AI tạo automation với trigger và action đúng. Chị kiểm tra lại trong Home Assistant rồi dùng luôn. Nhờ tính năng sao lưu khi sửa, chị cũng yên tâm hơn.
Cấu hình nhà thông minh trước kia là việc của người rành YAML, giờ chỉ cần biết mình muốn gì.
Ông T
B.Gỡ lỗi một automation không chạy
Anh Hùng có automation cảm biến chuyển động lúc chạy lúc không. Thay vì lục log, anh nói:
The motion sensor automation isn't working, debug itREADME mô tả AI sẽ phân tích dấu vết chạy (trace), tìm chỗ sai và gợi ý cách sửa. Anh đọc đề xuất, đồng ý thì nhờ AI sửa. Kết quả là tiết kiệm được nhiều thời gian dò từng bước.
C.Bổ sung hành động vào automation có sẵn
Bạn đã có automation buổi sáng và muốn thêm việc bật máy pha cà phê. Bạn nói:
Make my morning routine automation also turn on the coffee makerAI đọc automation hiện có, thêm hành động mới rồi cập nhật. Bạn không phải mở editor và tự ghép. Tương tự, bạn có thể nhờ "tạo script chế độ xem phim: giảm đèn, đóng rèm, bật TV" để có một script dùng lại được.
D.Cập nhật dashboard bằng lời
Bạn muốn thêm thẻ thời tiết vào trang chủ. Chỉ cần nói "Add a weather card to my dashboard". Theo README, AI cập nhật dashboard Lovelace với thẻ mới. Nếu chưa tự tin, hãy bật Read Only Mode để AI chỉ xem, không sửa, cho tới khi bạn quen.
VI.Lỗi hay gặp và cách xử lý
AI không thấy Home Assistant, kết nối treo. Nguyên nhân phổ biến theo README là khai báo hai lần cho cùng một server trong một ứng dụng AI (ví dụ vừa uvx, vừa URL của tích hợp). Hãy giữ đúng một mục, xóa mục còn lại.
Thiết bị khác không kết nối được tới server. Ở bước thiết lập, cả "Remote access" và "Local network" đều mặc định tắt. Vào tùy chọn của mục HA-MCP Server, bật một trong hai rồi lấy lại URL ở màn hình Configure.
Không tìm thấy HA-MCP khi cài. Kiểm tra phiên bản Home Assistant: cần từ 2026.8.0 trở lên. Bản cài cũ còn có thể hiện tên "HA-MCP Custom Component", hãy tìm bằng từ "HA-MCP". Sau khi cài, đừng quên restart Home Assistant.
Dùng stdio mà hay đứt kết nối. README nói thẳng stdio có vấn đề truyền tải mà HTTP không có. Hãy chuyển sang tích hợp, app hoặc phương thức HTTP.
ChatGPT không kết nối vì cần URL công khai. Connector của ChatGPT thường đòi URL truy cập được từ internet. README chỉ một tích hợp cộng đồng (OpenAI Tunnel for HA-MCP của @norpol) cho trường hợp đứng sau tường lửa; đây không phải phần chính thức của repo, nên bạn đọc kỹ trước khi dùng. Ngoài ra có thể dùng Nabu Casa hoặc reverse proxy sẵn có.
Gặp lỗi khác, bạn xem phần FAQ & Troubleshooting trên trang dự án.
VII.Có nên dùng không
Điểm mạnh: miễn phí và nguồn mở (MIT); cài chủ yếu bằng giao diện Home Assistant; hỗ trợ nhiều ứng dụng AI; có chế độ chỉ đọc, bật/tắt từng công cụ và tự sao lưu trước khi sửa. Phạm vi rộng, từ automation tới dashboard, lịch sử, sao lưu.
Giới hạn: bạn cần có Home Assistant đang chạy và đủ mới (2026.8.0 trở lên cho cách khuyên dùng). Server cần quyền quản trị, nên rủi ro nằm ở việc bảo vệ token/URL và nhớ rằng AI có thể sửa cấu hình thật. README cũng ghi một số tính năng như ha_config_set_yaml đang ở dạng beta. Tài liệu còn có nhiều phần nâng cao (OIDC, webhook proxy, công cụ sửa file và YAML tùy chọn) mà bài này chỉ nhắc qua.
Khi nào chọn cách khác: nếu chỉ cần vài automation đơn giản và bạn đã quen giao diện Home Assistant, cứ làm tay cũng nhanh. Nếu không muốn AI có quyền sửa, hãy bật Read Only Mode hoặc đừng cài. Còn nếu bạn hay phải sửa, gỡ lỗi, thêm cấu hình, ha-mcp đáng thử, và bản demo giúp bạn thử mà không cần đụng nhà thật.
Câu hỏi thường gặp
ha-mcp có miễn phí không?
Repo là nguồn mở với giấy phép MIT. README nói thử bản demo không cần gói trả phí. Riêng Claude Code trên Linux cần gói Claude trả phí, còn chi phí của ứng dụng AI khác bạn tự kiểm tra ở nhà cung cấp.
Cài ha-mcp có cần GPU không?
Tư liệu không nhắc tới yêu cầu GPU hay phần cứng riêng. Server chỉ là cầu nối giữa ứng dụng AI và Home Assistant, còn phần xử lý AI do ứng dụng bạn dùng đảm nhiệm.
ha-mcp chạy được trên Windows không?
Phần tích hợp chạy trong Home Assistant, nên bạn thao tác qua trình duyệt trên bất kỳ máy nào. Để thử bản demo, README có script PowerShell cho Windows, cùng script cho macOS và Linux.
Cần loại Home Assistant nào?
Cách khuyên dùng (tích hợp HA-MCP) cần Home Assistant 2026.8.0 trở lên và chạy trên mọi kiểu cài: OS, Supervised, Container, Core. Cách app (add-on) dành cho Home Assistant OS và Supervised.
Dùng ha-mcp có an toàn không?
Server hoạt động bằng quyền của một tài khoản quản trị, nên bạn cần giữ kín token và URL kết nối. README khuyên tạo tài khoản riêng chỉ cho HA-MCP, có thể bật Read Only Mode, tắt từng công cụ và có sao lưu tự động khi sửa. Repo cũng có PRIVACY.md và SECURITY.md để bạn đọc thêm.
Có dùng được với ChatGPT không?
Có, README nêu rõ ChatGPT nằm trong các ứng dụng hỗ trợ. Connector của ChatGPT thường cần URL công khai; nếu không muốn mở ra ngoài, README nhắc tới một tích hợp cộng đồng tên OpenAI Tunnel for HA-MCP.
Cài app (add-on) và cài tích hợp khác nhau thế nào?
README khuyên dùng tích hợp vì chạy được trên mọi kiểu cài Home Assistant và đủ tính năng. App là lựa chọn thứ hai, không cần token nhưng chỉ cho Home Assistant OS và Supervised. Chỉ chọn một cách cho mỗi ứng dụng AI để tránh treo kết nối.


