Home Assistant MCP

لماذا تستخدمه

الميزات الأساسية

بحث مرن عن الكيانات + بحث عميق في الإعدادات عبر آلاف الكيانات
كتابة وتحرير الأتمتة والسكريبتات والمشاهد والمساعدين في YAML
محرر لوحة التحكم: إنشاء البطاقات والتخطيطات والعروض
استعلامات التاريخ والإحصاءات مع مخرجات جاهزة للرسوم البيانية
لوحة الطاقة ولقطات الكاميرا وتتبع تشغيل الأتمتة

عرض مباشر

كيف يبدو في الممارسة

ha-mcp.replay ▶ جاهز

0/0

التثبيت

اختر العميل

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

افتح Claude Desktop → Settings → Developer → Edit Config. أعد التشغيل بعد الحفظ.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

يستخدم Cursor نفس مخطط mcpServers مثل Claude Desktop. إعدادات المشروع أولى من الإعدادات العامة.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

انقر على أيقونة MCP Servers في شريط Cline الجانبي، ثم "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

نفس الصيغة مثل Claude Desktop. أعد تشغيل Windsurf لتطبيق التغييرات.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "ha-mcp",
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  ]
}

يستخدم Continue مصفوفة من كائنات الخادم بدلاً من خريطة.

~/.config/zed/settings.json

{
  "context_servers": {
    "ha-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "ha-mcp"
        ]
      }
    }
  }
}

أضف إلى context_servers. يعيد Zed التحميل تلقائيًا عند الحفظ.

claude mcp add ha-mcp -- uvx ha-mcp

أمر من سطر واحد. تحقق باستخدام claude mcp list. احذف باستخدام claude mcp remove.

حالات الاستخدام

استخدامات عملية: Home Assistant MCP

التحكم بالأجهزة دون حفظ معرفات الكيانات

👤 أي شخص لديه Home Assistant مُعبَّأ بالأجهزة ⏱ ~5 min beginner

متى تستخدمه: تعرف ما تريد ("اخفت مطبخ إلى 30%") لكن لا تعرف entity_id الدقيق.

المتطلبات الأساسية

رمز وصول طويل الأمد لـ Home Assistant — Profile → Security → Create Token؛ احفظه كمتغير بيئة HA_TOKEN
HA_URL مضبوط — اضبط HA_URL=http://homeassistant.local:8123 (أو URL الخاص بك)

الخطوات

البحث عن الكيان

Use ha-mcp. Find entities matching 'kitchen light'. Show entity_id, area, and current state.✓ تم النسخ

→ 1-3 كيانات مرشحة مع الحالة الراهنة
تطبيق التغيير

Set kitchen ceiling lights to 30% brightness, warm white.✓ تم النسخ

→ نجاح استدعاء الخدمة؛ تأكيد الحالة

النتيجة: التحكم بالأجهزة بالنية لا بالحفظ.

المزالق

تطابق كيانات متعددة — تبديل الخاطئ — أكّد دائماً قائمة entity_id قبل أي إجراء جماعي؛ استخدم فلاتر المنطقة

كتابة أتمتة معقدة من مواصفة بلغة طبيعية

👤 مستخدمو HA الذين يتجنبون YAML ⏱ ~15 min intermediate

متى تستخدمه: تريد "إذا غادرت المنزل وكان بعد الغروب ووعاء قطتي فارغاً، أرسل لي إشعاراً" — ولا تريد كتابة YAML.

الخطوات

وصف النية

Use ha-mcp. List my person tracker, sun, and cat feeder entities so we can wire an automation.✓ تم النسخ

→ الكيانات ذات الصلة مع مخطط الحالة
توليد YAML

Create automation 'cat-feeder-sundown-alert' with that logic. Don't deploy yet — show me the YAML.✓ تم النسخ

→ YAML صالح لأتمتة HA في المحادثة
النشر والتتبع

Deploy it. Then trigger it manually and show the trace so I can verify the conditions fired.✓ تم النسخ

→ الأتمتة في الواجهة؛ التتبع يظهر الفروع المتوقعة

النتيجة: أتمتة تعمل دون تحرير /config/automations.yaml يدوياً.

المزالق

الأتمتة مُنشرة لكن لا تُطلق — خطأ في اسم الكيان — استخدم أداة trace؛ تحقق أن entity_id يطابق تماماً

التحقيق في ارتفاع الطاقة باستخدام التاريخ والإحصاءات

👤 مالكو المنازل الذكية الذين لديهم لوحة طاقة HA ⏱ ~25 min intermediate

متى تستخدمه: ارتفعت فاتورتك وتريد معرفة ما الذي تغيّر.

الخطوات

جلب الإجماليات

Use ha-mcp. Compare total kWh per circuit for last 30 days vs the prior 30. Flag deltas >20%.✓ تم النسخ

→ جدول لكل دائرة مع الفروق البارزة
التعمق في الأسوأ

For the worst-offending circuit, plot hourly usage for the last 7 days and identify the new pattern.✓ تم النسخ

→ ملف استهلاك بالساعة + ملاحظة شفهية عن الشذوذ
إيجاد الجهاز المسؤول

Which entity on that circuit changed behavior? Cross-reference automations that touch it.✓ تم النسخ

→ جهاز محدد + أتمتة محددة

النتيجة: إجابة ملموسة مثل "شاحن السيارة الكهربائية نفّذ جدولاً جديداً"، لا مجرد شك مبهم.

المزالق

الإحصاءات بجودة تغطية المستشعرات فحسب — اعترف بالثغرات؛ اقترح أماكن إضافة مراقبة

إعداد 'وضع الإجازة' يشمل الأضواء والأقفال والستائر والإشعارات

👤 على وشك السفر في رحلة ⏱ ~30 min intermediate

متى تستخدمه: ستغادر خلال ساعة وتريد محاكاة التواجد + سلوك وضع الغياب.

الخطوات

جرد الكيانات المتأثرة

Use ha-mcp. List lights in living areas, all door locks, all blinds. Note which are HA-controllable.✓ تم النسخ

→ قائمة كيانات مصنفة مع علامة قابلية التحكم
بناء السكريبت

Create a script 'vacation_mode_on' that arms locks, randomizes evening lights 18:30–22:30, sets blinds to 50%, and pauses cleaning automations.✓ تم النسخ

→ السكريبت في HA؛ التشغيل اليدوي ينجح
إضافة محفز

Bind it to an input_boolean 'vacation_mode' so I can toggle from the dashboard.✓ تم النسخ

→ زر تبديل في لوحة التحكم؛ تفعيله يشغّل السكريبت

النتيجة: وضع إجازة بنقرة واحدة؛ تغادر ولوحة التحكم مفعّلة.

المزالق

قفل الأبواب تلقائياً مع وجود أشخاص داخل المنزل — أضف فحص تواجد الأشخاص؛ لا تقفل أبداً عندما يكون أحدهم في المنزل

التركيبات

اجمعها مع خوادم MCP أخرى لتحقيق نتائج x10

ha-mcp + filesystem

نسخ احتياطي لـ automations.yaml و scripts.yaml على git

Export all automations and scripts via ha-mcp, write to ./ha-config/, commit.✓ تم النسخ

الأدوات

ما يوفره هذا الـ MCP

الأداة	المدخلات	متى تستدعيها	التكلفة
search_entities	query: str, area?, domain?	الخطوة الأولى في كل تدفق تقريباً — إيجاد entity_id	1 HA API call
call_service	domain, service, target, data	تطبيق أي تغيير على جهاز أو مشهد	1 API call
create_automation	yaml_or_object	كتابة الأتمتة برمجياً	1 API call
get_history	entity_id, start, end	جلب تاريخ الحالة للتحليل	1 API call
get_statistics	statistic_id, period (5min\|hour\|day\|month)	البيانات المجمعة طويلة الأمد (الطاقة والمناخ)	1 API call
trace_automation	automation_id, run_id?	تصحيح سبب تشغيل أو عدم تشغيل أتمتة	1 API call

التكلفة والحدود

تكلفة التشغيل

حصة API: لا حصة صارمة — واجهة REST المحلية
الرموز لكل استدعاء: متغير؛ سجل الكيانات قد يكون ضخماً إذا لم تفلتر
التكلفة المالية: مجاني (مفتوح المصدر)
نصيحة: استخدم دائماً search_entities مع فلاتر — تفريغ السجل الكامل مكلف بالرموز

الأمان

الصلاحيات والأسرار ونطاق الأثر

الحد الأدنى من الصلاحيات: Long-Lived Access Token (نطاق HA الكامل)

تخزين بيانات الاعتماد: متغير بيئة HA_TOKEN

نقل البيانات الخارجي: فقط إلى URL مثيل HA الخاص بك — يُفضَّل الإبقاء على الشبكة المحلية

لا تمنح أبدًا:

رمز HA لأي نموذج لغوي سحابي لا تثق به — هذا يتحكم في الوصول المادي (الأقفال، الكراج)

الرموز المميزة طويلة الأمد لا تُجدَّد تلقائياً — جدّدها يدوياً إذا شككت في تسربها
اختبر الأتمتة والأقفال بطريقة لا تؤدي إلى إغلاقك خارجاً (احتفظ بنسخة احتياطية)

استكشاف الأخطاء

الأخطاء الشائعة وحلولها

تعذّر الاتصال بـ HA

تحقق أن HA_URL يمكن الوصول إليه من حيث يعمل MCP؛ افحص trusted_proxies إذا كنت خلف reverse proxy

تحقق: curl $HA_URL/api/ -H 'Authorization: Bearer $HA_TOKEN'

401 Unauthorized

الرمز منتهي أو ملغى — أنشئ رمز طويل الأمد جديداً من الملف الشخصي

استدعاء الخدمة يعيد 400

عدم تطابق توقيع الخدمة — استخدم لوحة أدوات المطور للتحقق من المخطط ثم أعد المحاولة

الأتمتة منشورة لكن لا تُطلق

استخدم trace_automation لمعرفة الشرط الذي فشل؛ شائع: خطأ في entity_id أو خطأ في المنطقة الزمنية لشرط الشمس

البدائل