SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor · Cập nhật ngày 2026-11-16

Cách kết nối Claude với Home Assistant qua MCP

Hướng dẫn kết nối Claude với Home Assistant dùng MCP server tích hợp từ bản 2025.2. Cấu hình HTTPS, thiết lập OAuth và phân quyền read-only để đảm bảo an toàn hệ thống.

Cách kết nối Claude với Home Assistant qua MCP

Để kết nối Claude với Home Assistant qua MCP, hãy bật tính năng tích hợp Model Context Protocol có sẵn của Home Assistant và thêm địa chỉ của nó vào Claude dưới dạng một custom connector. Claude sau đó sẽ đăng nhập thông qua quy trình OAuth của chính Home Assistant. OAuth là tiêu chuẩn mở cho phép cấp quyền truy cập cho ứng dụng mà không cần chia sẻ mật khẩu của bạn. Home Assistant cần có một địa chỉ HTTPS công khai trước. Việc thiết lập địa chỉ này chiếm phần lớn công việc, vì Claude truy cập vào nhà bạn từ cloud của Anthropic, ngay cả khi bạn sử dụng Claude Desktop.

MCP (Model Context Protocol) là một tiêu chuẩn mở cho phép một AI client gọi các công cụ trên một server khác. Home Assistant đã tích hợp MCP Server kể từ bản release 2025.2. Các công cụ của nó có thể đọc trạng thái ngôi nhà của bạn và, với các tùy chọn phù hợp, có thể điều khiển nó. Vì vậy, quyết định thực sự nằm ở vấn đề bảo mật. Ai có thể truy cập vào địa chỉ bạn mở và tài khoản đứng sau nó được phép làm gì? Nếu bạn vẫn đang cân nhắc vị trí của MCP trong số các cách khác để mở rộng Claude, hãy bắt đầu với cách MCP so sánh với agent skills và rules files.

Hướng dẫn này đã được kiểm chứng với tài liệu của Home Assistant, Anthropic, Tailscale, Caddy và Nabu Casa vào ngày 15 tháng 11 năm 2026. Bản release Home Assistant hiện tại vào ngày đó là 2026.11.1. Một số tùy chọn dưới đây chỉ mới xuất hiện vài tháng, vì vậy hãy cập nhật Home Assistant trước khi bắt đầu.

Tại sao Claude cần Home Assistant trên internet công cộng

Bài viết trợ giúp của Anthropic về các custom connector đã nêu rõ: "Claude kết nối với máy chủ MCP từ xa của bạn từ cơ sở hạ tầng đám mây của Anthropic, thay vì từ thiết bị cục bộ của bạn." Tài liệu của Home Assistant cũng nói điều tương tự về ứng dụng desktop: "Claude kết nối với máy chủ MCP của bạn từ đám mây, ngay cả khi bạn sử dụng Claude Desktop."

Hai yêu cầu được đặt ra từ điều này. Máy chủ của bạn phải truy cập được qua internet công cộng từ các dải IP của Anthropic. Nó cũng phải phản hồi trên cổng HTTPS tiêu chuẩn, cổng 443. Vì vậy http://homeassistant.local:8123 không bao giờ có thể hoạt động như một URL kết nối. Các máy chủ của Anthropic không thể phân giải một tên miền chỉ tồn tại trên mạng gia đình của bạn và cổng 8123 không phải là 443.

Claude Desktop cũng có một cơ chế thứ hai. Các máy chủ MCP cục bộ được liệt kê trong claude_desktop_config.json có sử dụng mạng cục bộ của bạn. Chúng tách biệt với các connector và không khả dụng trên claude.ai hoặc trong các phiên Cowork chạy trên đám mây. Tài liệu của Home Assistant chỉ mô tả đường dẫn connector cho Claude Desktop, vì vậy hướng dẫn này sử dụng đường dẫn đó.

Claude Code thì khác. Nó chạy trên máy tính hoặc máy chủ của riêng bạn và tự mở kết nối MCP, vì vậy URL chỉ cần truy cập được từ máy đó. Home Assistant lưu ý rằng "Claude Code chỉ kết nối với các máy chủ MCP qua HTTPS". Do đó, một địa chỉ HTTPS riêng tư bên trong mạng của riêng bạn cũng hoạt động. Sự khác biệt giữa Tailscale Serve và Tailscale Funnel chính là sự lựa chọn này: Serve cung cấp một địa chỉ HTTPS riêng tư trên tailnet của bạn, còn Funnel cung cấp một địa chỉ công cộng.

Các custom connector khả dụng trên các gói Free, Pro, Max, Ultra, Team và Enterprise. Người dùng gói Free bị giới hạn ở một custom connector. Đó là một trong những giới hạn được đề cập trong những gì gói Claude Free bao gồm.

Bật tích hợp MCP Server

  1. Trong Home Assistant, truy cập Settings > Devices & services và chọn Add Integration.
  2. Chọn Model Context Protocol từ danh sách và thực hiện theo các bước trên màn hình.
  3. Truy cập Settings > System > AI. Nếu thẻ Model Context Protocol hiển thị nút Enable, hãy chọn nó.
  4. Sao chép Main URL. Đường dẫn của nó là /api/mcp.

URL kết nối đầy đủ là hostname công khai của bạn cộng với đường dẫn đó, ví dụ https://ha.example.com/api/mcp. Hostname phụ thuộc vào đường dẫn truy cập mà bạn chọn ở phần dưới.

URL chính mặc định truy cập những gì

URL chính có ba tùy chọn và chúng chỉ áp dụng cho /api/mcp. Hãy đọc kỹ trước khi kết nối bất kỳ thứ gì.

  • Expose all AI tools (Phơi bày tất cả công cụ AI) được bật theo mặc định. Khi đó, URL chính sẽ phơi bày mọi bộ công cụ, bao gồm cả các bộ được thêm vào bởi các tích hợp sau này. Một bộ trong số đó có tên là Home Assistant. Tài liệu ghi rằng nó "có thể đọc tất cả các thực thể, nhật ký, lịch sử và thực hiện bất kỳ hành động nào."
  • Require an administrator account (Yêu cầu tài khoản quản trị viên) được bật theo mặc định. Khi URL chính phơi bày bộ Home Assistant, tài khoản quản trị viên luôn được yêu cầu, bất kể công tắc này được thiết lập thế nào.
  • Read-only (Chỉ đọc) được tắt theo mặc định. Khi bạn bật tùy chọn này, URL chính chỉ phơi bày các công cụ được đánh dấu là không làm thay đổi bất kỳ điều gì, ví dụ như lấy trạng thái hiện tại của ngôi nhà.
  • Các thiết lập cũ giữ hai trong số các công tắc này ở trạng thái tắt. Đối với Expose all AI tools, tài liệu ghi rằng nó "giữ ở trạng thái tắt để các client của bạn giữ lại những công cụ bạn đã chọn." Công tắc quản trị viên "giữ ở trạng thái tắt để các client của bạn tiếp tục hoạt động." Nếu mục nhập MCP Server của bạn cũ hơn các tùy chọn này, hãy mở tùy chọn của nó và kiểm tra lại.

Hãy tắt Expose all AI tools để chọn từng bộ công cụ một. Bộ Device control (Điều khiển thiết bị) cung cấp cho AI các công cụ tương tự như trợ lý giọng nói của bạn, và nó "chỉ truy cập các thực thể mà bạn đã phơi bày cho trợ lý giọng nói." Bộ Home Assistant không có giới hạn này.

Ngoài ra còn có các URL riêng biệt cho từng bộ công cụ đơn lẻ. /api/mcp/assist chỉ phơi bày Device control. Các URL này bỏ qua ba tùy chọn nêu trên. Chúng không bao giờ ở chế độ chỉ đọc. Tất cả các URL này, ngoại trừ URL Device control, đều yêu cầu tài khoản quản trị viên.

Hãy kiểm tra những gì Device control có thể truy cập trước khi bạn tin tưởng nó. Assist phơi bày các thực thể mới theo mặc định, bao gồm cả các thiết bị che chắn (covers). Tài liệu của Home Assistant nêu rõ: "Covers bao gồm cửa gara và cổng, vì vậy Home Assistant cũng tự động phơi bày chúng." Khóa, bảng điều khiển báo động và các script không được phơi bày tự động. Hãy mở cài đặt phơi bày của Assist và xóa bất kỳ thực thể nào mà bạn không muốn cửa sổ chat có thể mở được.

Sử dụng tài khoản riêng, không dùng tài khoản chủ sở hữu

Khi bạn chọn Connect trong Claude, bạn sẽ đăng nhập vào Home Assistant trên trình duyệt. Quyền truy cập mà Claude nhận được thuộc về tài khoản bạn đã dùng để đăng nhập. Nếu bạn đăng nhập bằng tài khoản chủ sở hữu (owner), Claude sẽ hoạt động với tư cách chủ sở hữu, có mọi quyền hạn mà chủ sở hữu có.

Hãy tạo một người dùng riêng trong Home Assistant với thông tin đăng nhập riêng và chỉ sử dụng tài khoản đó cho Claude. Để thu hồi quyền truy cập của Claude sau này, bạn chỉ cần xóa tài khoản đó và tài khoản của bạn sẽ không bị ảnh hưởng. Sau đó, hãy chọn một trong hai thiết lập sau.

Hẹp: Claude điều khiển một vài thiết bị. Giữ tài khoản ở mức người dùng bình thường, không phải quản trị viên. Trong các tùy chọn URL chính, hãy tắt Expose all AI tools, chỉ chọn Device control và tắt Require an administrator account. Khi đó, Claude chỉ có thể tiếp cận các thực thể được phơi bày (exposed) cho giọng nói. Hãy bật thêm Read-only nếu bạn chỉ muốn Claude báo cáo trạng thái. Bạn có thể sử dụng /api/mcp/assist thay thế, vốn không yêu cầu quyền quản trị viên. Tuy nhiên, URL đó sẽ bỏ qua tùy chọn Read-only.

Rộng: Claude đọc log và lịch sử. Bộ công cụ Home Assistant luôn yêu cầu tài khoản quản trị viên. Hãy tạo tài khoản chuyên dụng là quản trị viên, giữ nó tách biệt với chủ sở hữu và bật Read-only. Khi đó, Claude có thể đọc các thực thể, log và lịch sử. Các công cụ thay đổi trạng thái sẽ không được phơi bày.

Trong bước Connect, hãy kiểm tra xem bạn đang đăng nhập bằng tài khoản nào. Thực hiện bước này trong cửa sổ trình duyệt ẩn danh sẽ giúp tránh việc vô tình sử dụng lại phiên đăng nhập của chủ sở hữu.

Đừng dựa vào các thông báo xác nhận trong client làm cơ chế bảo vệ. Trong luồng kết nối, tài liệu Home Assistant nêu rằng Claude sẽ hỏi quyền trước khi gọi bất kỳ công cụ nào. Claude Code thì khác. Từ phiên bản v2.1.283, chế độ auto là chế độ quyền mặc định cho các phiên terminal tương tác và VS Code, và chế độ auto sẽ không hỏi trước mỗi hành động. Bản thân Home Assistant sẽ thực thi các quyền của tài khoản và tùy chọn Read-only, bất kể client quyết định ra sao.

Claude cloud nên kết nối với Home Assistant như thế nào?

Phần còn lại của mục này là mô hình đe dọa của chính hướng dẫn này, được xây dựng dựa trên tài liệu của từng dịch vụ. Không nhà cung cấp nào trong số này nêu rõ trong tài liệu của họ về những gì đường truyền của họ không bảo vệ được, vì vậy hãy coi phần này là suy luận, không phải là tuyên bố từ nhà cung cấp.

Mọi đường truyền dưới đây đều có một điểm chung: bất kỳ ai có thể truy cập URL đều có thể truy cập trang đăng nhập của Home Assistant. Vì vậy, hãy thiết lập bảo vệ đăng nhập trước. Trong Settings > System > Network, tại mục HTTP server, hãy bật Enable IP banning. Sau đó, thiết lập Login attempts before ban, mục này chấp nhận giá trị từ 1 đến 1000 và chỉ xuất hiện khi tùy chọn Unlimited login attempts bị tắt. Khi đứng sau bất kỳ proxy hoặc tunnel nào, hãy bật thêm Trust X-Forwarded-For và thêm địa chỉ của proxy vào Trusted proxies. Tài liệu của Home Assistant cảnh báo: "Các yêu cầu từ reverse proxy sẽ bị chặn nếu các tùy chọn này không được thiết lập." Trước phiên bản Home Assistant 2026.8, các thiết lập này nằm trong khối http: của configuration.yaml.

Dịch vụ của Nabu Casa hiện có tên là Home Assistant Link (trước đây là Home Assistant Cloud). Vào ngày 15 tháng 11 năm 2026, trang giá của họ niêm yết mức 6.50 USD mỗi tháng hoặc 65.00 USD mỗi năm, chưa bao gồm thuế. Trang này cũng liệt kê bản dùng thử miễn phí 31 ngày không cần thẻ tín dụng. Truy cập từ xa là một trong những lợi ích được liệt kê.

Những gì nó công khai: toàn bộ giao diện web và trang đăng nhập Home Assistant của bạn trên một địa chỉ HTTPS công cộng. Những gì nó không bao gồm: mật khẩu yếu trên tài khoản mà Claude sử dụng, hoặc một token bị rò rỉ từ nơi khác. Trang hỗ trợ của Nabu Casa không tải được trong lúc hướng dẫn này được soạn thảo. Hãy đọc tài liệu của chính họ để tìm hiểu những gì relay của họ có thể và không thể thấy.

Tailscale Funnel

Funnel định tuyến lưu lượng từ internet công cộng đến một dịch vụ cục bộ, và Tailscale cho biết tính năng này có sẵn trên tất cả các gói. Nó yêu cầu Tailscale v1.38.3 trở lên, MagicDNS, chứng chỉ HTTPS hợp lệ cho tailnet của bạn, và một thuộc tính funnel node trong tệp chính sách tailnet. Nó chỉ có thể nghe trên các cổng 443, 8443 và 10000. Cổng 443 là cổng mà Claude cần. Nếu các yêu cầu đó còn mới lạ với bạn, thế nào là Tailscale và cách tailnet hoạt động sẽ giải thích chúng. Trên máy chạy Home Assistant, hãy chạy:

sudo tailscale funnel 8123

Tailscale sẽ in ra một địa chỉ https://<machine>.<tailnet>.ts.net công cộng để proxy đến http://127.0.0.1:8123. Sử dụng hostname đó trong URL của connector. Thêm 127.0.0.1 vào Trusted proxies trong Home Assistant, vì mọi yêu cầu giờ đây đều đến từ proxy Tailscale cục bộ. Lệnh này chạy ở foreground cho đến khi bạn nhấn Ctrl+C.

Những gì nó công khai: toàn bộ cổng Home Assistant cho bất kỳ ai trên internet. Khách truy cập qua Funnel không cần Tailscale, vì vậy tailnet riêng của bạn không cung cấp thêm rào cản nào cho họ. Lưu lượng Funnel cũng có giới hạn băng thông mà bạn không thể cấu hình.

Cloudflare Tunnel

Cloudflare Tunnel sử dụng kết nối chỉ đi ra (outbound-only). Daemon cloudflared bên trong mạng của bạn kết nối ra ngoài tới Cloudflare, vì vậy bạn không mở cổng inbound nào và không cần IP công cộng tại nhà.

Những gì nó công khai: hostname mà bạn xuất bản ra toàn bộ internet, trừ khi bạn thêm các quy tắc phía trước nó. Một quy tắc bắt buộc người dùng phải đăng nhập tại Cloudflare trước phải cho phép các dải IP đã công bố của Anthropic đi qua. Cloud cloud của Claude không thể điền vào trang đăng nhập, vì vậy các yêu cầu MCP của nó sẽ dừng lại ở Cloudflare. Thêm địa chỉ mà cloudflared sử dụng để truy cập Home Assistant vào Trusted proxies.

Reverse proxy trên VPS

Với đường truyền này, bạn kiểm soát máy chủ đối diện với internet. Một VPS (máy chủ riêng ảo) nhỏ với IP công cộng chạy reverse proxy, và nó truy cập Home Assistant tại nhà qua một liên kết riêng như tailnet. Không có gì tại nhà được mở ra internet. Bạn cũng có thể giới hạn ai có thể truy cập proxy.

Anthropic công bố các địa chỉ IP mà họ sử dụng cho các yêu cầu đi ra, "ví dụ, khi thực hiện các lệnh gọi công cụ MCP đến các máy chủ bên ngoài." Vào ngày 15 tháng 11 năm 2026, trang này liệt kê hai dải IPv4 đi ra ở dạng CIDR, và không có dải IPv6 đi ra nào. Hãy sao chép các dải hiện tại từ trang địa chỉ IP của Anthropic vào ngày bạn thiết lập. Trang này cũng liệt kê các địa chỉ cũ không còn sử dụng, vì vậy chỉ lấy các địa chỉ đi ra hiện tại.

Với Caddy đã cài đặt trên VPS, /etc/caddy/Caddyfile có thể loại bỏ mọi kết nối không đến từ các dải đó:

ha.example.com {
    @blocked not remote_ip <anthropic-range-1> <anthropic-range-2> 203.0.113.25
    abort @blocked
    reverse_proxy 100.101.102.103:8123
}

Thay thế <anthropic-range-1> và <anthropic-range-2> bằng các dải IPv4 đi ra từ trang của Anthropic, 203.0.113.25 bằng IP công cộng của riêng bạn, và 100.101.102.103 bằng địa chỉ của Home Assistant trên tailnet của bạn. IP của riêng bạn nằm trong danh sách vì bước Connect mở trang đăng nhập Home Assistant trong trình duyệt của bạn. Yêu cầu đó đến từ bạn, không phải từ Anthropic. Nếu Connect bị treo trên một trang không bao giờ tải, địa chỉ của bạn đang thiếu trong danh sách. Caddy thiết lập các header X-Forwarded-For, X-Forwarded-Proto và X-Forwarded-Host theo mặc định, và nó proxy các kết nối WebSocket. Nó cũng lấy chứng chỉ TLS (transport layer security) cho chính hostname đó, miễn là bản ghi DNS của hostname trỏ đến VPS.

caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

caddy validate sẽ hoàn tất mà không có lỗi. Từ một địa chỉ bên ngoài danh sách, curl -I https://ha.example.com/ sẽ không nhận được phản hồi HTTP nào cả, vì abort đóng kết nối. Cuối cùng, thêm địa chỉ tailnet của VPS vào Trusted proxies trong Home Assistant.

Những gì nó không bảo vệ được: mọi người dùng Claude đều chia sẻ các dải IP của Anthropic. Danh sách cho phép (allowlist) chỉ ngăn chặn các trình quét ngẫu nhiên. Bất kỳ ai biết URL của bạn và thêm nó làm connector của riêng họ vẫn có thể truy cập trang đăng nhập của bạn, vì vậy mật khẩu tài khoản và IP banning vẫn quan trọng. Bạn cũng sẽ phải quản lý việc cập nhật bản vá cho VPS.

Chọn đường truyền nào

Nabu Casa là thiết lập ngắn gọn nhất và không cần máy chủ riêng. Funnel và Cloudflare Tunnel tránh việc mở cổng tại nhà, nhưng cả hai đều đặt toàn bộ trang đăng nhập lên internet công cộng. Proxy trên VPS tốn nhiều công sức nhất và có mức độ phơi nhiễm nhỏ nhất, vì chỉ các dải IP của Anthropic và địa chỉ của riêng bạn mới có thể mở kết nối. Trên mọi đường truyền, tài khoản chuyên dụng và công tắc Read-only bảo vệ bạn tốt hơn là việc lựa chọn đường truyền.

Thêm connector vào Claude

  1. Trên claude.ai, mở Customize > Connectors và chọn + Add > Add custom connector. Trong Claude Desktop, tài liệu của Home Assistant hướng dẫn vào Settings > Connectors, sau đó chọn Add > Add custom connector.
  2. Đặt tên là Home Assistant và dán URL đầy đủ, ví dụ https://ha.example.com/api/mcp.
  3. Thiết lập Authentication thành Sign in now và OAuth client thành Use Claude's published identity, sau đó chọn Add.
  4. Trên trang của connector mới, chọn Connect và đăng nhập vào Home Assistant bằng tài khoản chuyên dụng.

Đối với gói Team hoặc Enterprise, Owner sẽ thêm connector trong mục Organization settings > Connectors. Sau đó, mỗi thành viên tìm connector này trong Customize > Connectors và chọn Connect để thực hiện đăng nhập Home Assistant cho tài khoản cá nhân.

Bạn chọn published identity vì cách Home Assistant xử lý OAuth. Home Assistant triển khai OAuth 2.0 với PKCE (proof key for code exchange). Nó hỗ trợ OAuth Client ID Metadata Documents, vì vậy client ID và callback URL được thiết lập tự động. Home Assistant không sử dụng client secret. Nó cũng không hỗ trợ RFC 7591 Dynamic Client Registration, và tài liệu nêu rõ các client yêu cầu nghiêm ngặt tính năng này "không thể tự động đăng ký". Đối với các MCP client khác, tài liệu cho biết Client ID phải là URL gốc của ứng dụng client, "không bao giờ được là URL instance Home Assistant của bạn."

Thêm Home Assistant vào Claude Code

claude mcp add --transport http home-assistant https://ha.example.com/api/mcp
claude mcp login home-assistant

claude mcp login chạy luồng OAuth của máy chủ từ shell của bạn. Nó cũng chấp nhận --no-browser cho các phiên SSH trên máy chủ từ xa. Theo mặc định, claude mcp add sử dụng phạm vi cục bộ, giới hạn máy chủ trong dự án hiện tại trên máy này. Thêm --scope user để làm cho nó khả dụng trong mọi dự án. Bên trong Claude Code, /mcp hiển thị trạng thái kết nối của máy chủ. Nếu Claude Code chạy trên Linux và bạn chưa thiết lập nó, quá trình cài đặt được đề cập trong chạy Claude trên máy tính để bàn Linux và trong CLI.

Long-lived token hay OAuth: các hướng dẫn cũ đang nói về cái nào?

Các hướng dẫn cũ yêu cầu bạn tạo một long-lived access token. Điều đó đúng tại thời điểm tài liệu được viết. Không có bản release Home Assistant nào chuyển đổi từ token sang OAuth trong một bước duy nhất. Thay đổi này diễn ra theo từng giai đoạn:

  • Các tài liệu MCP Server đầu tiên, viết cho bản 2025.2, ghi: "Hiện tại, chúng ta có thể dùng Long-lived access token để kiểm soát quyền truy cập vào API."
  • Từ ngày 31 tháng 3 năm 2025, tài liệu mô tả OAuth thông qua IndieAuth. Tài liệu cũng lưu ý rằng một số MCP client hỗ trợ access token nhưng không hỗ trợ OAuth.
  • PKCE với phương thức S256 xuất hiện lần đầu trong source code của Home Assistant tại tag 2026.10.0. Nó không có trong source code tại bản 2026.9.0.
  • Trang MCP Server hiện tại không đề cập đến long-lived token.

Một hướng dẫn yêu cầu dán token vào request header là mô tả cho thiết lập cũ. Hãy sử dụng các bước OAuth hiện tại ở trên thay thế.

Khi nào thì server ha-mcp cộng đồng là lựa chọn tốt hơn?

ha-mcp là một dự án riêng biệt theo giấy phép MIT. File README tại tag v9.2.0 liệt kê 87 công cụ. File README trên nhánh mặc định lại ghi 86, vì vậy số lượng thay đổi giữa các bản build. Hãy chọn ha-mcp khi bạn cần một danh sách công cụ lớn hơn, được xây dựng cho mục đích cụ thể so với các bộ công cụ tích hợp sẵn, và bạn chấp nhận một mô hình xác thực khác.

Bản cài đặt được khuyến nghị ở v9.2.0 là tích hợp HA-MCP. Nó chạy bên trong Home Assistant và yêu cầu Home Assistant 2026.8.0 trở lên. Từ phiên bản 2026.8 đến 2026.10, bạn cài đặt nó thông qua HACS (Home Assistant Community Store). Từ 2026.11, nó nằm trong Settings > Marketplace. Sau khi khởi động lại, hãy thêm HA-MCP Server trong Settings > Devices & services > Add Integration. Tích hợp này hoạt động với quyền quản trị viên, và tài liệu của dự án khuyến nghị nên dùng một tài khoản HA-MCP riêng biệt. Dự án cũng phát hành một Docker image, một gói PyPI và một Home Assistant app (add-on), và file README của nó mô tả chế độ stdio cục bộ chỉ dành cho mục đích kiểm thử.

Cố định bản phát hành ổn định

Vào ngày 15 tháng 11 năm 2026, bản phát hành ổn định mới nhất là v9.2.0, được công bố vào ngày 11 tháng 11. Các bản build phát triển (.devN) được xuất bản sau mỗi lần push lên master, và năm tag dev đã xuất hiện trong vòng 24 giờ trước khi kiểm tra này. Lời khuyên của chính dự án rất rõ ràng: "Các bản phát hành dev (.devN) có thể chứa lỗi. Để sử dụng trong môi trường production, hãy gắn bó với các bản phát hành ổn định." Hãy cài đặt bản phát hành v9.2.0, không phải bản build .devN. Các tag :latest và :stable của Docker image theo dõi các bản phát hành ổn định và không bao giờ dùng các bản build dev. Nếu bạn chạy nó với uvx, lệnh trong README kết thúc bằng @latest. Hãy thay thế nó bằng @9.2.0, vì cú pháp @ của uv yêu cầu một phiên bản chính xác. Gói PyPI yêu cầu Python 3.13 hoặc 3.14.

URL private_ chính là mật khẩu

Server tích hợp sẵn yêu cầu Claude đăng nhập. Chế độ ha-mcp chính thì không. Trên mạng nội bộ của bạn, địa chỉ của nó có dạng http://<ha-ip>:9584/private_<random>. Từ xa, nó là một webhook URL như https://<your-ha-domain>/api/webhook/<webhook-id>. Tài liệu của dự án nói rằng "đường dẫn chính là thông tin xác thực", và họ yêu cầu bạn "Hãy coi URL như mật khẩu: không chia sẻ nó hoặc dán nó vào nơi có thể bị ghi log." Bất kỳ ai có URL đầy đủ đều có thể truy cập server MCP của bạn, và không có trang đăng nhập nào ở giữa.

Điều này làm thay đổi mô hình đe dọa. Một URL bị dán vào chat chung hoặc để lại trong log của proxy sẽ cấp toàn quyền truy cập. Nếu bị lộ, hãy tạo một webhook ID mới để thay thế. Thêm /readonly vào cuối endpoint để có kết nối ẩn các công cụ ghi và chặn các lệnh gọi ghi. Truy cập từ xa hoạt động thông qua Nabu Casa remote UI hoặc một reverse proxy mà bạn đang chạy. Đối với Cloudflare Tunnel, README dẫn đến Setup Wizard của nó.

ha-mcp cũng có chế độ OAuth, được gắn nhãn beta. Nó vẫn yêu cầu mỗi người dùng dán một Home Assistant long-lived access token vào biểu mẫu xác nhận. Đây là một cơ chế khác so với việc đăng nhập của server tích hợp sẵn.

Tại sao connector không đăng nhập được?

Trang đăng nhập không hiển thị, hoặc Claude báo không thể kết nối tới máy chủ. Cloud của Anthropic không thể truy cập URL của bạn. Hãy kiểm tra kết nối tới cổng 443 từ một mạng bên ngoài, và kiểm tra danh sách cho phép (allowlist) nếu bạn có sử dụng.

Đăng nhập thất bại với lỗi OAuth khi đứng sau proxy. Tài liệu của Home Assistant đã nêu rõ nguyên nhân: các header của reverse-proxy (X-Forwarded-Host, X-Forwarded-Proto) bị thiếu hoặc không khớp. Tài liệu cũng bổ sung rằng "Các OAuth client tuân thủ tiêu chuẩn sẽ từ chối metadata này." URL mà Home Assistant tạo ra phải khớp chính xác với hostname và scheme mà Claude đã sử dụng. Hãy sửa lại các header của proxy và cài đặt Trusted proxies.

Yêu cầu tới /register trả về lỗi 404. Client đã thử thực hiện Dynamic Client Registration, tính năng mà Home Assistant không hỗ trợ. Trong Claude, hãy thiết lập OAuth client thành Use Claude's published identity.

Một vấn đề đã biết. Vào ngày 15 tháng 11 năm 2026, issue #183050 báo cáo rằng connector claude.ai bị lỗi khi chạy với /api/mcp trên Core 2026.11.0. Vấn đề này vẫn đang mở và được đánh dấu là cần thêm thông tin, chưa có bản sửa lỗi nào được xác nhận. Hãy kiểm tra connector của bạn trước khi đưa vào sử dụng chính thức.

FAQ

Claude Desktop có kết nối với Home Assistant từ máy tính của tôi không?

Không, đối với custom connector. Cả Anthropic và Home Assistant đều cho biết Claude kết nối từ cloud của Anthropic, kể cả trong Claude Desktop. Đó là lý do Home Assistant cần một địa chỉ HTTPS công khai trên cổng 443. Các ngoại lệ là máy chủ cục bộ trong claude_desktop_config.json và Claude Code, chúng kết nối trực tiếp từ máy của bạn.

Claude có thể mở cửa gara của tôi thông qua Home Assistant MCP không?

Có, nếu tài khoản và bộ công cụ cho phép. Assist mặc định hiển thị các thiết bị dạng cover, và cover bao gồm cửa gara và cổng, vì vậy bộ công cụ Device control thường có thể truy cập chúng. Bộ công cụ Home Assistant có thể thực hiện bất kỳ hành động nào. Nếu bạn không muốn Claude điều khiển chúng, hãy xóa các thực thể đó khỏi Assist hoặc bật chế độ Read-only cho URL chính.

Tôi có còn cần long-lived access token cho Home Assistant MCP server không?

Không, đối với server tích hợp sẵn. Tài liệu hiện tại sử dụng OAuth 2.0 với PKCE và không đề cập đến long-lived token. Token là phương thức trong tài liệu 2025.2 đầu tiên. Server ha-mcp của cộng đồng thì khác: chế độ OAuth beta của nó vẫn yêu cầu bạn dán một long-lived token.

Tôi bị khóa khỏi Home Assistant sau khi connector thất bại nhiều lần. Chuyện gì đã xảy ra?

Tính năng IP banning đã chặn địa chỉ đăng nhập thất bại. Tài liệu Home Assistant cho biết nguyên nhân phổ biến nhất là thông tin OAuth sai, ví dụ như client ID hoặc URL của Home Assistant. Hãy mở ip_bans.yaml trong thư mục cấu hình Home Assistant của bạn, xóa mục nhập cho địa chỉ bị chặn và khởi động lại Home Assistant. Hãy sửa lại cài đặt connector trước khi thử lại.

Bài viết này có hữu ích không?

#claude#mcp#home-assistant#smart-home#remote-access