ha-mcp Home Assistant: خادم MCP غير رسمي ينشره المستودع homeassistant-ai/ha-mcp على GitHub، ويتيح لمساعد ذكاء اصطناعي (مثل Claude وChatGPT وGemini CLI) قراءة تثبيت Home Assistant والتحكم فيه بلغة طبيعية. بحسب صفحة GitHub في 27 أكتوبر 2026، يضم المستودع نحو 5300 نجمة (تعرض GitHub القيمة «5.3k» مقرّبة) و255 نسخة متفرعة (fork)، بترخيص MIT.
بالنسبة إلى فريق SRE، تتجاوز الفائدة مجال المنزل الذكي. هذا المستودع مثال تعليمي: يتلقى الوكيل مفاتيح «بيئة إنتاج صغيرة» من أضواء وأقفال وأتمتة ونسخ احتياطية. والأسئلة المفيدة هي: من يستطيع استدعاء الخادم، وبأي صلاحيات، وماذا يحدث إذا كان الإجراء لا رجعة فيه؟ يتبع هذا المقال ملف README وملف SECURITY.md والأسئلة الشائعة وملف LICENSE في المستودع، وقد قُرئت جميعها اليوم.
توضيح للأمانة: span.observer مدوّنة مستقلة لا صلة لها بـ Home Assistant ولا بمؤلفي المشروع، ولم تثبّت ha-mcp ولم تشغّله. يصف المشروع نفسه بأنه «The Unofficial and Awesome Home Assistant MCP Server». اللقطات أدناه مقتطفات مولّدة من ملفات المستودع.
ha-mcp Home Assistant: ما يقوله المستودع
- الترخيص: ملف LICENSE ترخيص MIT.
- اللغة والإطار: Python 3.13 أو أحدث (
requires-python = ">=3.13,<3.15"فيpyproject.toml)، ومبني على FastMCP بحسب README. - الإصدار: يذكر
pyproject.tomlوملف CHANGELOG الإصدار 8.7.0 بتاريخ 14 أكتوبر 2026. لم أتمكن من قراءة رقم إصدار (release) في صفحة GitHub؛ وآخر commit قرأته بتاريخ 26 أكتوبر 2026. - النطاق: يعلن README عن 87 أداة: البحث في الكيانات واستدعاء الخدمات والأتمتة والسكربتات ولوحات المعلومات والسجل التاريخي والسجلات والنسخ الاحتياطية وسجل الأجهزة وإعادة تشغيل Home Assistant.
- الفرق عن خادم MCP المدمج: بحسب README، يعتمد خادم Home Assistant الخاص على Assist ولا يرى إلا الكيانات المكشوفة له؛ أما ha-mcp فيغطي «كل ما في Home Assistant»، بما في ذلك إنشاء الإعدادات وتعديلها.
هذا الفرق هو لبّ الموضوع: كلما زادت قدرة الوكيل على الضبط اتسع سطح المخاطر.
خادم MCP لـ Home Assistant: سطح المخاطر
ثلاث نقاط في SECURITY.md تستحق القراءة قبل أي تثبيت.
- العميل المصادق عليه «طرف موثوق». يقول الملف إن ha-mcp لا يحاول الدفاع ضد عميل MCP خبيث أو مخترق، وإن حقن التعليمات (prompt injection) مسؤولية العميل.
- الصلاحيات تأتي من الرمز. يستخدم ha-mcp رمز الوصول طويل الأمد الذي يُمنح له؛ ومع رمز مسؤول يستطيع تنفيذ عمليات إدارية. يتوقع المشروع رمز مسؤول، ولتقييد الوكيل ينصح بسياسات أمان الأدوات أو بتعطيل أدوات بدل استخدام رمز غير إداري.
- الشبكة المحلية هي المنطقة الموثوقة. في الوضع القياسي تقوم المصادقة على سر في مسار العنوان؛ وأي جهاز يصل إلى هذا المسار يُعامل كجهاز موثوق. افتراضيًا تستمع نقاط دخول HTTP على
0.0.0.0؛ ويقيّدهاMCP_HOST=127.0.0.1بالجهاز المحلي.

يضيف الملف نفسه أن جميع العملاء الذين يشتركون في السر ذاته يحصلون في الوضع القياسي على وصول متطابق، من دون عزل بين العملاء. وللوصول من الإنترنت يوجّه SECURITY.md إلى وضع OAuth (موصوف بأنه تجريبي) أو OIDC خلف وكيل عكسي TLS. وللمبادئ العامة اقرأ تأمين خادم MCP ودروس SRE من MCP للجمهور العام.
تقييد الوكيل: القراءة فقط والسياسات والموافقة
في فئة «Safety» يذكر README وضع القراءة فقط، وتفعيل الأدوات أو تعطيلها واحدةً واحدة، وسياسات أمان الأدوات (موافقة المستخدم)، ونسخًا احتياطية تلقائية للتعديلات.
القراءة فقط لكل اتصال
بحسب README، تؤدي إضافة /readonly إلى عنوان خادم HTTP إلى حصر ذلك الاتصال بوضع القراءة فقط، بينما يحتفظ العملاء الآخرون بالوصول العادي. تُخفى أدوات الكتابة وتُحظر استدعاءاتها، بما فيها الاستدعاءات عبر أدوات مخزّنة مؤقتًا.

انتبه: يوضح README أن هذا وضع اتصال وليس صلاحية على بيانات الاعتماد؛ فالبيانات نفسها تعمل على العنوان العادي. لذلك يبقى تسريب السر منحًا لوصول كامل.
وضع القراءة فقط العام
تصف وثائق التطبيق (add-on) الخيار read_only_mode، وهو معطّل افتراضيًا: يزيل أدوات الكتابة من القائمة ويحظر أي كتابة بخطأ READ_ONLY_MODE. ومن الحالات المذكورة: التحليل والتدقيق والعروض التجريبية. ويلزم إعادة تشغيل التطبيق.
موافقة بشرية على الإجراءات الحساسة
تصف الأسئلة الشائعة قواعد «Tool Security Policies» التي تحتجز الاستدعاء إلى أن تتم الموافقة عليه في واجهة الإعدادات. كما يُعلَن كل طلب على ناقل أحداث Home Assistant باسم ha_mcp_approval_requested مع الحقول token وtool_name وargs وcreated_at وexpires_at.

تحذّر الأسئلة الشائعة من أن المعاملات الطويلة تُقتطع لكنها لا تُخفى: فالمعامل القصير يُبثّ على الناقل كما هو. والموافقة من إشعار معطّلة افتراضيًا وتتطلب رمز PIN.
التثبيت خطوة بخطوة
يوصي README بالمكوّن «HA-MCP Custom Component» المثبَّت عبر HACS، وهو يشغّل الخادم داخل Home Assistant. ويذكر دليل البدء السريع فيه الإصدار 9.0.0 (28 أكتوبر 2026) وما بعده: هذا التاريخ لاحق ليوم قراءتي، فتحقق من الشاشات على إصدارك.
- ثبّت المكوّن من HACS (مستودع مخصص
https://github.com/homeassistant-ai/ha-mcp، الفئة Integration)، ثم أعد تشغيل Home Assistant. - حدّد حساب المسؤول الذي يعمل الخادم باسمه. يرى README أن الأسلم إنشاء حساب مخصص (الإعدادات، الأشخاص) مع تفعيل «Allow login» و«Local access only» و«Administrator». أما رمز على حسابك الشخصي فهو «يعمل من أي مكان إن تسرّب».
- أضف التكامل (الإعدادات، الأجهزة والخدمات) واختر طريقة اتصال العملاء: وصول عن بعد عبر webhook (ابدأ بـ «Secret URL») و/أو وصول عبر الشبكة المحلية. كلاهما معطّل في البداية.
- انسخ عنوان الاتصال من شاشة Configure والصقه في عميل الذكاء الاصطناعي.
طرق أخرى بحسب README: تطبيق Home Assistant (HAOS وSupervised)، أو Docker، أو PyPI مع uvx، أو stdio محلي (غير موصى به، وتُذكر مشكلات في النقل). اضبط طريقة واحدة فقط لكل عميل. وللتجربة من دون المساس ببيتك يقدّم README سكربتات تثبيت تشير إلى خادم تجريبي؛ اقرأ السكربت قبل تشغيله.
الحدود والنقاط المفتوحة
- مدى الاعتماد على المشروع: مشروع نشط (مساهمون كثر وCHANGELOG مفصّل) لكنه سريع التغيّر، وله عدة أوضاع للتثبيت والمصادقة. يعلن README عن تغيير غير متوافق في الإصدار 7.3.0 ويضع بعض الميزات في الوضع التجريبي (الملفات وYAML والأدوات المخصصة). وتقرّب GitHub عدد النجوم.
- تواريخ تستحق التحقق: يذكر README إصدارًا 9.0.0 بتاريخ 28 أكتوبر 2026، بينما الإصدار المقروء في الشيفرة هو 8.7.0.
- أدوات كتابة حساسة: تشمل الأدوات الـ 87 إعادة التشغيل وحذف الأجهزة والكيانات واستعادة النسخ الاحتياطية، وكتابة الملفات في الوضع التجريبي. بعض الإجراءات لا يُتراجع عنها بسهولة.
- السر في العنوان: تنصح الأسئلة الشائعة بعدم لصقه في لقطات الشاشة أو السجلات العامة أو المحادثات.
- البيانات: يقول PRIVACY.md إن ha-mcp لا يجمع قياسات عن بُعد (telemetry) حتى يونيو 2026 (الجمع المجهول «مخطَّط له»)، لكن ما يقرأه الوكيل يمرّ عبر عميل الذكاء الاصطناعي ومزوّده.
- مشروع غير رسمي: لا تطوّره Home Assistant ولا تضمنه.
مراقبة خادم MCP
لا تصف الوثائق التي قرأتها أي تصدير لتتبعات أو مقاييس OpenTelemetry. صحيح أن pyproject.toml يدرج المكتبة opentelemetry-api ضمن الاعتماديات، لكن لا شيء يقول إنها تصدّر تتبعات: لا تبنِ مراقبة عليها قبل التحقق. أما ما تصفه الوثائق فهو:
- سجلات الخادم: تبويب Logs في التطبيق، أو
docker logs ha-mcpمع Docker. وتذكر الأسئلة الشائعة سطرين عاديين: «Terminating session: None» (وضع HTTP بلا حالة) ورمز 405 على طلب GET. - تشخيص نقل HTTP: الخيار
HAMCP_HTTP_TRANSPORT_DIAGNOSTICS=true(معطّل افتراضيًا ويتطلب إعادة تشغيل) يسجّل بمستوى INFO عدد البايتات والمدة وحالات الانقطاع ونوع الاستثناء، مع معرّف تتبع يولّده الخادم. من دون أجسام الطلبات أو بيانات الاعتماد أو المسارات السرية. - أحداث الموافقة: يتيح
ha_mcp_approval_requestedعلى ناقل Home Assistant عدّ الإجراءات المحتجزة والتنبيه عليها. - من جهة Home Assistant: تقرأ الأداتان
ha_get_logsوha_get_automation_tracesالسجلات وتتبعات الأتمتة.
ولتتبع استدعاءات الأدوات من البداية إلى النهاية، يجب أن يصدر العميل أو الوكيل الـ spans: اقرأ مراقبة وكلاء MCP باستخدام OpenTelemetry. ومن المشاريع المجاورة: Agent Reach.
أفضل الممارسات
- ابدأ بالقراءة فقط (
/readonlyأوread_only_mode) ولا تفتح الكتابة إلا عند الحاجة. - أنشئ حساب مسؤول مخصصًا بدل استخدام رمزك الشخصي.
- أبقِ الوصول محليًا؛ وإن لزم الوصول عن بعد ففضّل تسجيل دخول Home Assistant أو OIDC على السر وحده.
- اشترط موافقة بشرية على الأدوات المدمّرة (الحذف والاستعادة وإعادة التشغيل).
- بدّل أي سر انكشف وراقب السجلات؛ وانظر ضوابط وكلاء الذكاء الاصطناعي.
الأسئلة الشائعة
هل ha-mcp مشروع رسمي من Home Assistant؟
لا. يقدّم المستودع نفسه بوصفه «Unofficial». ولدى Home Assistant خادم MCP مدمج خاص بها يقارنه README مع ha-mcp.
هل يستطيع الوكيل تعديل كل شيء فعلًا؟
يستطيع ما يسمح به الرمز المقدَّم، بحسب SECURITY.md. ومع مسؤول يشمل ذلك عمليات إدارية؛ ويضيّق وضع القراءة فقط وتعطيل الأدوات وسياسات الموافقة هذا النطاق.
هل يرسل المشروع بيانات إلى مؤلفه؟
بحسب PRIVACY.md (يونيو 2026) لا تُجمع أي قياسات عن بُعد، ولا تُرسل تقارير الأخطاء إلا بموافقتك. أما بياناتك فيعالجها عميل الذكاء الاصطناعي الذي توصله.
الخلاصة
يُظهر ha-mcp ما يحدث حين يُسلَّم نظام حقيقي إلى وكيل: يقوم معظم الأمان على صلاحيات الرمز وسرّية العنوان وضوابط الموافقة. تعامل معه كمكوّن يجب تقييده منذ اليوم الأول. المصادر: مستودع homeassistant-ai/ha-mcp (README وSECURITY.md وdocs/FAQ.md وLICENSE)، قُرئت في 27 أكتوبر 2026.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا لـ Home Assistant ولا لمؤلفي ha-mcp ولا للمشاريع المذكورة. العلامات التجارية المذكورة تعود إلى مالكيها. الأدوات تتطور بسرعة: تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.