اتصال Claude به Home Assistant از طریق پروتکل MCP
با استفاده از قابلیت داخلی MCP در نسخه 2025.2، هوش مصنوعی Claude را به خانه هوشمند خود متصل کنید. برای امنیت بیشتر، حتما از یک حساب کاربری با دسترسی محدود استفاده کنید.
نحوه اتصال Claude به Home Assistant با استفاده از MCP
برای اتصال Claude به Home Assistant از طریق MCP، قابلیت یکپارچهسازی داخلی Model Context Protocol را در Home Assistant فعال کنید و آدرس آن را به عنوان یک custom connector در Claude وارد نمایید. سپس Claude از طریق فرایند ورود OAuth خودِ Home Assistant احراز هویت میشود. OAuth یک استاندارد باز برای اعطای دسترسی به یک برنامه بدون نیاز به اشتراکگذاری رمز عبور است. Home Assistant ابتدا به یک آدرس HTTPS عمومی نیاز دارد. بخش عمده کار مربوط به همین آدرس است، زیرا Claude حتی هنگام استفاده از نسخه Claude Desktop، از طریق فضای ابری Anthropic به خانه شما متصل میشود.
MCP (مخفف Model Context Protocol) یک استاندارد باز است که به یک کلاینت هوش مصنوعی اجازه میدهد ابزارهای موجود در یک سرور دیگر را فراخوانی کند. Home Assistant از نسخه 2025.2، یکپارچهسازی MCP Server را ارائه کرده است. ابزارهای این پروتکل میتوانند وضعیت خانه شما را بخوانند و با تنظیمات مناسب، آن را کنترل کنند. بنابراین تصمیم اصلی مربوط به امنیت است. چه کسی میتواند به آدرسی که باز کردهاید دسترسی داشته باشد و حساب کاربری پشت آن چه مجوزهایی دارد؟ اگر هنوز در حال بررسی جایگاه MCP در میان روشهای مختلف توسعه قابلیتهای Claude هستید، با مقایسه MCP با agent skills و rules files شروع کنید.
این راهنما در تاریخ 22 نوامبر 2026 بر اساس مستندات Home Assistant، Anthropic، Tailscale، Caddy و Nabu Casa بررسی شده است. نسخه فعلی Home Assistant در آن روز 2026.11.2 بود. چندین گزینه ذکر شده در زیر تنها چند ماه قدمت دارند، بنابراین پیش از شروع، Home Assistant را بهروزرسانی کنید.
چرا Claude برای دسترسی به Home Assistant به اینترنت عمومی نیاز دارد
مقاله راهنمای Anthropic درباره کانکتورهای سفارشی مستقیماً به این موضوع اشاره میکند: «Claude از زیرساخت ابری Anthropic به سرور MCP راه دور شما متصل میشود، نه از دستگاه محلی شما.» مستندات Home Assistant نیز درباره اپلیکیشن دسکتاپ همین را میگوید: «Claude از طریق فضای ابری به سرور MCP شما متصل میشود، حتی زمانی که از Claude Desktop استفاده میکنید.»
از این موضوع دو الزام نتیجه میشود. سرور شما باید از طریق محدودههای IP متعلق به Anthropic در اینترنت عمومی قابل دسترسی باشد. همچنین باید روی پورت استاندارد HTTPS یعنی 443 پاسخگو باشد. بنابراین http://homeassistant.local:8123 هرگز نمیتواند به عنوان یک URL کانکتور کار کند. سرورهای Anthropic نمیتوانند نامی را که فقط در شبکه خانگی شما وجود دارد حل کنند و پورت 8123 نیز پورت 443 نیست.
Claude Desktop مکانیزم دومی هم دارد. سرورهای MCP محلی که در claude_desktop_config.json فهرست شدهاند، از شبکه محلی شما استفاده میکنند. این سرورها از کانکتورها جدا هستند و در claude.ai یا در نشستهای Cowork که در فضای ابری اجرا میشوند، در دسترس نیستند. مستندات Home Assistant فقط مسیر کانکتور را برای Claude Desktop توصیف میکند، بنابراین این راهنما نیز از همان مسیر استفاده میکند.
Claude Code متفاوت است. این ابزار روی کامپیوتر یا سرور شخصی شما اجرا میشود و اتصال MCP را خودش برقرار میکند، بنابراین URL فقط باید از همان ماشین قابل دسترسی باشد. Home Assistant اشاره میکند که «Claude Code فقط از طریق HTTPS به سرورهای MCP متصل میشود». بنابراین یک آدرس HTTPS خصوصی در داخل شبکه خودتان نیز کار میکند. تفاوت بین Tailscale Serve و Tailscale Funnel دقیقاً همین انتخاب است: Serve یک آدرس HTTPS خصوصی در tailnet شما ارائه میدهد و Funnel یک آدرس عمومی.
کانکتورهای سفارشی در پلنهای Free، Pro، Max، Ultra، Team و Enterprise در دسترس هستند. کاربران پلن Free به یک کانکتور سفارشی محدود شدهاند. این یکی از محدودیتهایی است که در آنچه پلن Claude Free شامل میشود به آن پرداخته شده است.
فعالسازی یکپارچهسازی MCP Server
- در Home Assistant، به مسیر Settings > Devices & services بروید و Add Integration را انتخاب کنید.
- گزینه Model Context Protocol را از لیست انتخاب کرده و مراحل نمایش داده شده روی صفحه را دنبال کنید.
- به مسیر Settings > System > AI بروید. اگر کارت Model Context Protocol دکمه Enable را نشان میدهد، آن را انتخاب کنید.
- Main URL را کپی کنید. مسیر آن
/api/mcpاست.
آدرس کامل connector برابر است با نام دامنه عمومی شما به اضافه آن مسیر؛ برای مثال https://ha.example.com/api/mcp. نام دامنه به مسیر دسترسی که در ادامه انتخاب میکنید بستگی دارد.
آنچه URL اصلی بهصورت پیشفرض در معرض دید قرار میدهد
URL اصلی دارای سه گزینه است که فقط برای /api/mcp اعمال میشوند. پیش از اتصال هر چیزی، آنها را مطالعه کنید.
- Expose all AI tools بهصورت پیشفرض فعال است. در این حالت، URL اصلی تمام مجموعهابزارها، از جمله مجموعههایی که بعداً توسط integrationها اضافه میشوند را در معرض دید قرار میدهد. یکی از این مجموعهها Home Assistant نام دارد. این مجموعه میتواند تمام entityها، لاگها و تاریخچه را بخواند و هر عملیاتی را انجام دهد.
- Require an administrator account بهصورت پیشفرض فعال است. هنگامی که URL اصلی مجموعه Home Assistant را در معرض دید قرار میدهد، صرفنظر از وضعیت این سوئیچ، همیشه به یک حساب کاربری مدیر (administrator) نیاز است.
- Read-only بهصورت پیشفرض غیرفعال است. هنگامی که آن را فعال میکنید، URL اصلی فقط ابزارهایی را در معرض دید قرار میدهد که به عنوان ابزارهای بدون تغییر (مانند دریافت وضعیت فعلی خانه) علامتگذاری شدهاند.
- تنظیمات قدیمیتر دو مورد از این سوئیچها را غیرفعال نگه میدارند. در مورد Expose all AI tools، مستندات بیان میکنند که «غیرفعال میماند تا کلاینتهای شما مجموعهابزارهای AI انتخابی شما را حفظ کنند.» سوئیچ administrator نیز «غیرفعال میماند تا کلاینتهای شما به کار خود ادامه دهند.» اگر ورودی MCP Server شما قدیمیتر از این گزینهها است، گزینههای آن را باز کرده و بررسی کنید.
برای انتخاب مجموعهابزارها به صورت تکی، گزینه Expose all AI tools را غیرفعال کنید. مجموعه Device control همان ابزارهایی را در اختیار AI قرار میدهد که دستیار صوتی شما دارد و «فقط به entityهایی دسترسی پیدا میکند که شما برای دستیارهای صوتی در معرض دید قرار دادهاید.» مجموعه Home Assistant چنین محدودیتی ندارد.
همچنین URLهای جداگانهای برای مجموعهابزارهای تکی وجود دارد. /api/mcp/assist فقط Device control را در معرض دید قرار میدهد. این URLها سه گزینه فوق را نادیده میگیرند. آنها هرگز read-only نیستند. تمام آنها به جز URL مربوط به Device control، به حساب کاربری مدیر نیاز دارند.
پیش از اعتماد به Device control، بررسی کنید که به چه مواردی دسترسی دارد. Assist بهصورت پیشفرض entityهای جدید را در معرض دید قرار میدهد و این شامل پوششها (covers) نیز میشود. مستندات Home Assistant صریح هستند: «پوششها شامل دربهای گاراژ و دروازهها هستند، بنابراین Home Assistant آنها را نیز بهطور خودکار در معرض دید قرار میدهد.» قفلها، پنلهای هشدار و اسکریپتها بهطور خودکار در معرض دید قرار نمیگیرند. تنظیمات Assist exposure را باز کرده و هر entity که نمیخواهید پنجره چت قادر به باز کردن آن باشد را حذف کنید.
از یک حساب کاربری اختصاصی استفاده کنید، نه حساب مالک
هنگامی که در Claude گزینه Connect را انتخاب میکنید، در مرورگر خود وارد Home Assistant میشوید. دسترسی که Claude دریافت میکند متعلق به حسابی است که با آن وارد شدهاید. اگر با حساب مالک (owner) وارد شوید، Claude با همان سطح دسترسی مالک عمل میکند و تمام اختیارات او را خواهد داشت.
یک شخص (Person) جداگانه در Home Assistant با نام کاربری مخصوص به خود ایجاد کنید و آن را فقط برای Claude به کار ببرید. برای لغو دسترسی Claude در آینده، کافی است همان یک حساب را حذف کنید و حساب کاربری اصلی شما دستنخورده باقی میماند. سپس یکی از دو پیکربندی زیر را انتخاب کنید.
محدود: Claude فقط چند دستگاه را کنترل میکند. حساب کاربری را در سطح کاربر عادی (normal user) نگه دارید و آن را مدیر (administrator) نکنید. در گزینههای اصلی URL، گزینه Expose all AI tools را خاموش کنید، فقط Device control را انتخاب کرده و Require an administrator account را غیرفعال کنید. در این حالت، Claude فقط به موجودیتهایی (entities) دسترسی خواهد داشت که برای کنترل صوتی در دسترس قرار گرفتهاند. اگر میخواهید Claude فقط وضعیت دستگاهها را گزارش کند، گزینه Read-only را نیز فعال کنید. همچنین میتوانید از /api/mcp/assist استفاده کنید که نیازی به دسترسی مدیر ندارد. البته آن URL گزینه Read-only را نادیده میگیرد.
گسترده: Claude لاگها و تاریخچه را میخواند. مجموعه ابزارهای Home Assistant همیشه به یک حساب مدیر نیاز دارند. حساب اختصاصی را مدیر کنید، آن را از حساب مالک جدا نگه دارید و گزینه Read-only را فعال کنید. در این صورت Claude میتواند موجودیتها، لاگها و تاریخچه را بخواند. ابزارهایی که تغییری در سیستم ایجاد میکنند، در دسترس قرار نمیگیرند.
در مرحله Connect، دقت کنید که با کدام حساب وارد میشوید. انجام این مرحله در یک پنجره مرورگر خصوصی (private window) باعث میشود که به اشتباه از نشست (session) حساب مالک استفاده نشود.
برای محافظت از سیستم، به اعلانهای تأیید (approval prompts) در کلاینت تکیه نکنید. در مستندات Home Assistant آمده است که Claude پیش از فراخوانی ابزارها درخواست اجازه میکند، مگر اینکه گزینه همیشه مجاز (always allow) را انتخاب کرده باشید. Claude Code متفاوت است. از نسخه v2.1.283 به بعد، حالت auto حالت پیشفرض برای ترمینال تعاملی و نشستهای VS Code است و در این حالت، Claude پیش از هر اقدام، درخواست تأیید نمیکند. خود Home Assistant فارغ از تصمیم کلاینت، حقوق حساب کاربری و وضعیت گزینه Read-only را اعمال میکند.
سرویس ابری Claude چگونه باید به Home Assistant دسترسی پیدا کند؟
باقی این بخش، مدل تهدید اختصاصی این راهنماست که بر اساس مستندات هر سرویس استخراج شده است. مقایسههای امنیتی زیر را به عنوان استدلال در نظر بگیرید، نه ادعاهای فروشنده.
تمام مسیرهای زیر یک وجه اشتراک دارند: هر کسی که بتواند به URL دسترسی پیدا کند، میتواند به صفحه ورود Home Assistant برسد. بنابراین ابتدا محافظت از ورود را تنظیم کنید. در Settings > System > Network، در بخش HTTP server، گزینه Enable IP banning را فعال کنید. سپس Login attempts before ban را تنظیم کنید که مقداری بین 1 تا 1000 میپذیرد و تنها زمانی ظاهر میشود که Unlimited login attempts غیرفعال باشد. پشت هر پروکسی یا تونلی، گزینه Trust X-Forwarded-For را نیز فعال کرده و آدرس پروکسی را به Trusted proxies اضافه کنید. مستندات Home Assistant هشدار میدهند: «اگر این گزینهها تنظیم نشوند، درخواستهای ارسالی از reverse proxyها مسدود میشوند.» پیش از نسخه 2026.8 Home Assistant، این تنظیمات در بلوک http: از فایل configuration.yaml قرار داشتند.
مثالهای زیر از پورت 8123 در Home Assistant استفاده میکنند. از نسخه 2026.8 Home Assistant، مقدار پیشفرض در Home Assistant Operating System برابر با 80 و در Container برابر با 8123 است، بنابراین در هر کجا که پورت 8123 ظاهر شد، آن را با پورت پیکربندیشده خود جایگزین کنید.
رابط کاربری از راه دور Nabu Casa (Home Assistant Link)
سرویس Nabu Casa اکنون Home Assistant Link (که قبلاً Home Assistant Cloud نامیده میشد) نام دارد. در تاریخ 15 نوامبر 2026، صفحه قیمتگذاری آن مبلغ 6.50 دلار آمریکا در ماه یا 65.00 دلار آمریکا در سال را بدون احتساب مالیات نشان میداد. همچنین یک دوره آزمایشی 31 روزه رایگان بدون نیاز به کارت بانکی نیز ذکر شده بود. دسترسی از راه دور یکی از مزایای فهرستشده است.
آنچه در معرض دید قرار میگیرد: کل رابط وب و صفحه ورود Home Assistant شما روی یک آدرس HTTPS عمومی. آنچه پوشش داده نمیشود: رمز عبور ضعیف در حسابی که Claude استفاده میکند، یا توکنی که از جای دیگری نشت کرده باشد. مستندات پشتیبانی Nabu Casa میگوید دسترسی از راه دور از رمزنگاری سرتاسری (end-to-end) استفاده میکند و کلید خصوصی فقط روی سیستم Home Assistant شما ذخیره میشود، بنابراین رله آنها نمیتواند دادههای شما را بخواند.
قابلیت Tailscale Funnel
قابلیت Funnel ترافیک را از اینترنت عمومی به یک سرویس محلی هدایت میکند و Tailscale میگوید این قابلیت در تمام طرحها در دسترس است. این سرویس به Tailscale نسخه 1.38.3 یا بالاتر، MagicDNS، گواهیهای HTTPS معتبر برای tailnet شما و یک ویژگی funnel node در فایل سیاست tailnet نیاز دارد. این سرویس فقط میتواند روی پورتهای 443، 8443 و 10000 گوش دهد. پورت 443 همان پورتی است که Claude به آن نیاز دارد. اگر این پیشنیازها برای شما جدید هستند، چیستی Tailscale و نحوه عملکرد یک tailnet آنها را توضیح میدهد. روی دستگاهی که Home Assistant را اجرا میکند، دستور زیر را اجرا کنید:
sudo tailscale funnel 8123Tailscale یک آدرس عمومی https://<machine>.<tailnet>.ts.net چاپ میکند که به http://127.0.0.1:8123 پروکسی میشود. از آن نام میزبان (hostname) در URL اتصال استفاده کنید. آدرس 127.0.0.1 را به Trusted proxies در Home Assistant اضافه کنید، زیرا اکنون تمام درخواستها از پروکسی محلی Tailscale میآیند. این دستور تا زمانی که Ctrl+C را فشار ندهید در پیشزمینه اجرا میشود.
آنچه در معرض دید قرار میگیرد: کل پورت Home Assistant برای هر کسی در اینترنت. بازدیدکنندگان Funnel نیازی به Tailscale ندارند، بنابراین tailnet خصوصی شما مانع اضافی برای آنها ایجاد نمیکند. ترافیک Funnel همچنین دارای محدودیتهای پهنای باند است که نمیتوانید آنها را پیکربندی کنید.
تونل Cloudflare
Cloudflare Tunnel از یک اتصال خروجیمحور استفاده میکند. دیمون cloudflared در داخل شبکه شما به Cloudflare متصل میشود، بنابراین هیچ پورت ورودی باز نمیکنید و نیازی به IP عمومی در خانه ندارید.
آنچه در معرض دید قرار میگیرد: نام میزبانی که منتشر میکنید برای کل اینترنت، مگر اینکه قوانینی را پیش از آن اعمال کنید. قانونی که باعث میشود فرد ابتدا در Cloudflare وارد شود، باید به محدودههای IP منتشرشده Anthropic اجازه عبور دهد. سرویس ابری Claude نمیتواند صفحه ورود را پر کند، بنابراین درخواستهای MCP آن در Cloudflare متوقف میشوند. آدرسی که cloudflared برای رسیدن به Home Assistant استفاده میکند را به Trusted proxies اضافه کنید.
یک reverse proxy روی VPS
در این مسیر، شما سروری را که رو به اینترنت است کنترل میکنید. یک VPS کوچک (سرور خصوصی مجازی) با IP عمومی، reverse proxy را اجرا میکند و از طریق یک لینک خصوصی مانند tailnet به Home Assistant در خانه میرسد. هیچ چیزی در خانه به روی اینترنت باز نمیشود. شما همچنین میتوانید محدود کنید که چه کسی اصلاً به پروکسی دسترسی داشته باشد.
Anthropic آدرسهای IP مورد استفاده خود برای درخواستهای خروجی را «برای مثال هنگام برقراری تماسهای ابزار MCP با سرورهای خارجی» منتشر میکند. در تاریخ 15 نوامبر 2026، این صفحه دو محدوده IPv4 خروجی را به فرمت CIDR فهرست کرده بود و هیچ محدوده IPv6 خروجی نداشت. محدودههای فعلی را از صفحه آدرس IP Anthropic در روزی که این تنظیمات را انجام میدهید، کپی کنید. این صفحه همچنین آدرسهای قدیمی که دیگر استفاده نمیشوند را فهرست میکند، بنابراین فقط آدرسهای خروجی فعلی را بردارید.
با نصب Caddy روی VPS، /etc/caddy/Caddyfile میتواند هر اتصالی که از آن محدودهها نباشد را رد کند:
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
}مقادیر <anthropic-range-1> و <anthropic-range-2> را با محدودههای IPv4 خروجی از صفحه Anthropic، مقدار 203.0.113.25 را با IP عمومی خود و 100.101.102.103 را با آدرس Home Assistant در tailnet خود جایگزین کنید. IP خودتان در لیست قرار دارد زیرا مرحله Connect صفحه ورود Home Assistant را در مرورگر شما باز میکند. آن درخواست از طرف شما میآید، نه از طرف Anthropic. اگر Connect روی صفحهای که هرگز بارگذاری نمیشود متوقف شد، آدرس شما در لیست جا افتاده است. Caddy بهطور پیشفرض هدرهای X-Forwarded-For، X-Forwarded-Proto و X-Forwarded-Host را تنظیم میکند و اتصالات WebSocket را پروکسی میکند. همچنین برای خود نام میزبان یک گواهی TLS (امنیت لایه انتقال) دریافت میکند، به شرطی که رکورد DNS نام میزبان به VPS اشاره کند و Caddy بتواند چالش اعتبارسنجی مرجع صدور گواهی را تکمیل کند.
caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddycaddy validate باید بدون خطا به پایان برسد. از یک آدرس خارج از لیست، curl -I https://ha.example.com/ نباید هیچ پاسخ HTTP دریافت کند، زیرا abort اتصال را میبندد. در نهایت، آدرس tailnet مربوط به VPS را به Trusted proxies در Home Assistant اضافه کنید.
آنچه در برابر آن محافظت نمیکند: هر کاربر Claude محدودههای IP Anthropic را به اشتراک میگذارد. لیست سفید (allowlist) اسکنرهای تصادفی را دور نگه میدارد. هر کسی که URL شما را یاد بگیرد و آن را به عنوان کانکتور خود اضافه کند، همچنان به صفحه ورود شما میرسد، بنابراین رمز عبور حساب و مسدودسازی IP همچنان اهمیت دارند. شما اکنون یک VPS دارید که باید آن را بهروز نگه دارید.
کدام مسیر را انتخاب کنیم
Nabu Casa کوتاهترین مسیر راهاندازی است و نیازی به سرور شخصی ندارد. Funnel و Cloudflare Tunnel از باز کردن پورت در خانه جلوگیری میکنند، اما هر دو کل صفحه ورود را در اینترنت باز قرار میدهند. پروکسی VPS بیشترین کار را میبرد و کمترین میزان در معرض قرارگیری را دارد، زیرا فقط محدودههای Anthropic و آدرس خودتان میتوانند اتصال برقرار کنند. در هر مسیری، حساب اختصاصی و سوئیچ Read-only بیش از انتخاب مسیر از شما محافظت میکنند.
افزودن کانکتور در Claude
- در سایت claude.ai، به بخش Customize > Connectors بروید و گزینه + Add > Add custom connector را انتخاب کنید. در نسخه Claude Desktop، طبق مستندات Home Assistant به مسیر Settings > Connectors رفته و سپس Add > Add custom connector را انتخاب کنید.
- نام آن را
Home Assistantبگذارید و URL کامل را وارد کنید، برای مثالhttps://ha.example.com/api/mcp. URL را ثبت کنید تا Claude سرور را بررسی کرده و تنظیمات احراز هویت آن را نمایش دهد. - گزینه Authentication را روی Sign in now و OAuth client را روی Use Claude's published identity تنظیم کرده و سپس Add را بزنید.
- در صفحه کانکتور جدید، گزینه Connect را انتخاب کرده و با حساب کاربری اختصاصی خود به Home Assistant وارد شوید.
در پلنهای Team یا Enterprise، مدیر (Owner) کانکتور را در بخش Organization settings > Connectors اضافه میکند. سپس هر عضو تیم آن را در بخش Customize > Connectors پیدا کرده و Connect را انتخاب میکند تا هر کاربر مراحل ورود به Home Assistant را طی کند.
دلیل انتخاب published identity نحوه مدیریت OAuth در Home Assistant است. Home Assistant از استاندارد OAuth 2.0 با PKCE (کلید اثبات برای تبادل کد) استفاده میکند. این سرویس از اسناد متادیتای OAuth Client ID پشتیبانی میکند، بنابراین Client ID و URL بازگشت (callback URL) بهصورت خودکار تنظیم میشوند. Home Assistant از client secret استفاده نمیکند. همچنین از RFC 7591 Dynamic Client Registration پشتیبانی نمیکند و طبق مستندات، کلاینتهایی که اکیداً به آن نیاز دارند «نمیتوانند بهصورت خودکار ثبت شوند.» برای سایر کلاینتهای MCP، مستندات تأکید دارند که Client ID باید URL پایه اپلیکیشن کلاینت باشد و «هرگز نباید URL نمونه Home Assistant شما باشد.»
افزودن Home Assistant به Claude Code
claude mcp add --transport http home-assistant https://ha.example.com/api/mcp
claude mcp login home-assistantclaude mcp login جریان OAuth سرور را از داخل shell شما اجرا میکند. این ابزار همچنین --no-browser را برای نشستهای SSH روی یک سرور راه دور میپذیرد. بهصورت پیشفرض، claude mcp add از scope محلی استفاده میکند که سرور را به پروژهٔ جاری روی این دستگاه محدود میسازد. برای در دسترس قرار دادن آن در تمامی پروژهها، --scope user را اضافه کنید. در داخل Claude Code، عبارت /mcp نشان میدهد که آیا سرور متصل است یا خیر. اگر Claude Code روی لینوکس اجرا میشود و هنوز آن را تنظیم نکردهاید، مراحل نصب در اجرای Claude روی دسکتاپ لینوکس و در محیط CLI پوشش داده شده است.
توکنهای با عمر طولانی یا OAuth: راهنماهای قدیمی به کدام اشاره دارند؟
راهنماهای قدیمی به شما میگویند که یک توکن دسترسی با عمر طولانی (Long-lived access token) ایجاد کنید. این روش در زمان نگارش آن راهنماها صحیح بود. هیچ نسخهٔ واحدی از Home Assistant بهطور ناگهانی از توکنها به OAuth تغییر وضعیت نداد. این تغییر طی چند مرحله انجام شد:
- نخستین مستندات MCP Server که برای نسخه 2025.2 نوشته شده بودند، میگفتند: "فعلاً میتوانیم از Long-lived access token برای کنترل دسترسی به API استفاده کنیم."
- روش PKCE با متد S256 برای اولین بار در تگ 2026.10.0 در سورسکد Home Assistant ظاهر شد. این قابلیت در سورسکد نسخه 2026.9.0 وجود ندارد.
- صفحه فعلی MCP Server دیگر به توکنهای با عمر طولانی اشارهای نمیکند.
راهنمایی که از شما میخواهد یک توکن را در هدر درخواست (request header) کپی کنید، مربوط به یک پیکربندی قدیمی است. بهجای آن، از مراحل فعلی OAuth که در بالا ذکر شد استفاده کنید.
چه زمانی سرور community ha-mcp انتخاب بهتری است؟
پروژه ha-mcp یک پروژه مستقل تحت مجوز MIT است. فایل README در تگ v9.2.0 تعداد 87 ابزار را فهرست کرده است. فایل README در شاخه پیشفرض نیز همین تعداد 87 را نشان میدهد؛ نسخه v9.3.0.dev3663 قبلاً عدد 86 را ذکر کرده بود، بنابراین این تعداد بین بیلدها تغییر میکند. زمانی ha-mcp را انتخاب کنید که به فهرست ابزارهای بزرگتر و تخصصیتری نسبت به مجموعههای داخلی نیاز دارید و مدل احراز هویت متفاوتی را میپذیرید.
نصب توصیهشده در نسخه v9.2.0، استفاده از integration مربوط به HA-MCP است. این برنامه درون Home Assistant اجرا میشود و به نسخه 2026.8.0 یا جدیدتر نیاز دارد. در نسخههای 2026.8 تا 2026.10، باید آن را از طریق HACS (فروشگاه انجمن Home Assistant) نصب کنید. از نسخه 2026.11 به بعد، این مورد در Settings > Marketplace قرار دارد. پس از یک بار راهاندازی مجدد، HA-MCP Server را از مسیر Settings > Devices & services > Add Integration اضافه کنید. این integration با دسترسیهای مدیر (administrator) عمل میکند و مستندات خود پروژه، استفاده از یک حساب کاربری اختصاصی برای HA-MCP را توصیه میکند. این پروژه همچنین یک Docker image، یک پکیج PyPI و یک اپلیکیشن (add-on) برای Home Assistant ارائه میدهد و فایل README آن، حالت stdio محلی را فقط برای تست توصیف کرده است.
استفاده از نسخه پایدار (Stable)
در تاریخ 22 نوامبر 2026، آخرین نسخه پایدار v9.2.0 بود که در 11 نوامبر منتشر شد. بیلدهای توسعه (.devN) با هر push به شاخه master منتشر میشوند. توصیه خود پروژه صریح است: "نسخههای توسعه (.devN) ممکن است حاوی باگ باشند. برای استفاده در محیط عملیاتی (production)، از نسخههای پایدار استفاده کنید." نسخه v9.2.0 را نصب کنید، نه یک بیلد .devN. تگهای :latest و :stable در Docker image نسخههای پایدار را دنبال میکنند و هرگز شامل بیلدهای توسعه نیستند. اگر آن را با uvx اجرا میکنید، دستور موجود در README به @latest ختم میشود. آن را با @9.2.0 جایگزین کنید، زیرا سینتکس @ در ابزار uv یک نسخه دقیق را میپذیرد. پکیج PyPI به Python 3.13 یا 3.14 نیاز دارد.
آدرس private_ URL همان رمز عبور است
سرور داخلی باعث میشود Claude وارد سیستم شود. در حالت secret URL در ha-mcp، این اتفاق نمیافتد. در شبکه داخلی شما، آدرس آن به شکل http://<ha-ip>:9584/private_<random> است. از راه دور، این آدرس یک URL وبهوک مانند https://<your-ha-domain>/api/webhook/<webhook-id> است. مستندات پروژه میگوید "مسیر همان اعتبارنامه است" و به شما توصیه میکند: "با URL مانند یک رمز عبور رفتار کنید: آن را به اشتراک نگذارید و در جایی که ممکن است لاگ شود، کپی نکنید." هر کسی که URL کامل را داشته باشد به سرور MCP شما دسترسی پیدا میکند و هیچ صفحه ورود به سیستمی در این میان وجود ندارد.
این موضوع مدل تهدید را تغییر میدهد. URLای که در یک چت اشتراکی کپی شود یا در لاگ یک پروکسی باقی بماند، دسترسی کامل میدهد. اگر یکی از آنها لو رفت، یک ID وبهوک جدید ایجاد کنید تا جایگزین شود. عبارت /readonly را به انتهای endpoint اضافه کنید تا اتصالی برقرار شود که ابزارهای نوشتن را مخفی کرده و فراخوانیهای نوشتن را مسدود میکند. همان اعتبارنامه همچنان در endpoint عادی کار میکند، بنابراین این پسوند دسترسی کسی که URL را دارد محدود نمیکند. دسترسی از راه دور از طریق Nabu Casa remote UI یا یک reverse proxy که از قبل اجرا کردهاید، امکانپذیر است. برای Cloudflare Tunnel، فایل README به Setup Wizard آن ارجاع میدهد.
پروژه ha-mcp همچنین دارای یک حالت OAuth است که با برچسب بتا مشخص شده است. این حالت همچنان از هر کاربر میخواهد که یک توکن دسترسی بلندمدت (long-lived access token) از Home Assistant را در یک فرم رضایتنامه کپی کند. این مکانیزم با ورود به سیستم در سرور داخلی متفاوت است. این integration همچنین ha_auth را ارائه میدهد که از سیستم ورود به سیستم خود Home Assistant استفاده کرده و فقط حسابهای مدیر را میپذیرد.
چرا اتصال برای ورود به سیستم با شکست مواجه میشود؟
صفحه ورود نمایش داده نمیشود یا Claude اعلام میکند که نمیتواند به سرور متصل شود. سرویس ابری Anthropic قادر به دسترسی به URL شما نیست. آن را از طریق پورت 443 و از شبکهای خارج از شبکه خانگی خود تست کنید و اگر از لیست مجاز (allowlist) استفاده میکنید، آن را بررسی نمایید.
ورود به سیستم به دلیل خطاهای OAuth در پشت پروکسی با شکست مواجه میشود. مستندات Home Assistant علت این مشکل را بیان کردهاند: هدرهای reverse-proxy (X-Forwarded-Host، X-Forwarded-Proto) وجود ندارند یا با تنظیمات مطابقت ندارند. در مستندات آمده است که «کلاینتهای OAuth استاندارد، این متادیتا را رد میکنند.» URLای که Home Assistant میسازد باید دقیقاً با نام میزبان (hostname) و طرح (scheme) استفاده شده توسط Claude مطابقت داشته باشد. هدرهای پروکسی و تنظیمات Trusted proxies را اصلاح کنید.
درخواست به /register خطای 404 برمیگرداند. کلاینت تلاش کرده است از Dynamic Client Registration استفاده کند که Home Assistant از آن پشتیبانی نمیکند. در Claude، کلاینت OAuth را روی حالت Use Claude's published identity تنظیم کنید.
یک مشکل شناختهشده و باز. در تاریخ 15 نوامبر 2026، issue #183050 گزارش میدهد که اتصال claude.ai در نسخه Core 2026.11.0 با /api/mcp دچار مشکل شده است. این مورد باز است و به عنوان نیازمند اطلاعات بیشتر علامتگذاری شده و هنوز هیچ اصلاحی برای آن تأیید نشده است. پیش از آنکه به اتصال خود وابسته شوید، آن را تست کنید.
FAQ
آیا Claude Desktop از کامپیوتر شخصی من به Home Assistant متصل میشود؟
خیر، برای یک connector سفارشی اینطور نیست. هم Anthropic و هم Home Assistant اعلام کردهاند که Claude حتی در نسخه Claude Desktop نیز از فضای ابری (cloud) شرکت Anthropic متصل میشود. به همین دلیل است که Home Assistant به یک آدرس HTTPS عمومی روی پورت 443 نیاز دارد. استثناها شامل سرورهای محلی در claude_desktop_config.json و Claude Code هستند که از روی ماشین شخصی شما متصل میشوند.
آیا Claude میتواند درب گاراژ من را از طریق Home Assistant MCP باز کند؟
بله، اگر حساب کاربری و مجموعه ابزارها (tool set) اجازه این کار را بدهند. قابلیت Assist بهطور پیشفرض پوششهای جدید (covers) را در معرض دید قرار میدهد و از آنجا که دربهای گاراژ و دروازهها جزو پوششها محسوب میشوند، مجموعه ابزار Device control معمولاً میتواند به آنها دسترسی داشته باشد. مجموعه ابزار Home Assistant میتواند هر عملیاتی را انجام دهد. اگر نمیخواهید Claude آنها را حرکت دهد، آن موجودیتها (entities) را از لیست موارد در معرض دید Assist خارج کنید یا حالت Read-only را برای URL اصلی فعال نمایید.
آیا هنوز برای سرور Home Assistant MCP به یک long-lived access token نیاز دارم؟
خیر، برای سرور داخلی (built-in) نیازی نیست. مستندات فعلی از OAuth 2.0 با PKCE استفاده میکنند و اشارهای به long-lived token ندارند. توکنها روشی بودند که در اولین مستندات نسخه 2025.2 استفاده میشدند. سرور جامعهمحور ha-mcp متفاوت است: حالت بتای OAuth در آن همچنان از شما میخواهد که یک long-lived token را وارد کنید.
پس از چند بار تلاش ناموفق برای اتصال، دسترسی من به Home Assistant مسدود شده است. چه اتفاقی افتاده است؟
قابلیت IP banning آدرسی را که در ورود ناموفق بوده، مسدود کرده است. مستندات Home Assistant بیان میکنند که محتملترین دلیل، اشتباه در جزئیات OAuth مانند client ID یا URL مربوط به Home Assistant است. فایل ip_bans.yaml را در دایرکتوری پیکربندی Home Assistant باز کنید، ورودی مربوط به آدرس مسدود شده را حذف کنید و Home Assistant را restart نمایید. پیش از تلاش مجدد، تنظیمات connector را اصلاح کنید.