Skip to main content
Glama
deenesjakoruzh
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

ha-nexus-agent

Home Assistant 的 MCP 服务器 — 通过 21 个领域的 202 个工具让 AI 助手全面掌控您的智能家居：实体（支持批量控制 + 语音暴露）、自动化与脚本（完整 CRUD + 追踪）、蓝图、仪表盘、辅助功能、区域、设备注册表、日历、待办事项列表、历史记录、系统管理、YAML 配置文件、基于 Git 的版本控制、实时 WebSocket 事件、能源仪表盘偏好设置、区域（地理围栏）、标签与分类、模糊搜索与发现、通过 Supervisor 管理插件以及 HACS 集成。

适用于 Claude Code CLI、Claude Desktop、VS Code、Cursor、Windsurf、OpenAI Codex CLI、Gemini CLI。

安装 — Home Assistant 插件（推荐）

  1. 在 Home Assistant 中前往 设置 → 插件 → 插件商店

  2. 点击右上角三个点菜单 (⋮) → 仓库

  3. 添加：

    https://github.com/Fistacho/ha-nexus-agent

  4. 找到 Nexus Agent 并点击 安装

  5. 点击 启动

  6. 点击 打开 Web UI

Web UI 会显示您的 API 密钥，并为每个 MCP 客户端生成可直接粘贴的配置。无需手动设置令牌 — 插件会自动连接到 Home Assistant。

安装 — 独立运行（HA 外部）

git clone https://github.com/Fistacho/ha-nexus-agent
cd ha-nexus-agent
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set HA_URL and HA_TOKEN
python server.py

打开 http://localhost:7123 以获取您的 API 密钥和 MCP 客户端配置。

获取 Home Assistant 令牌

  1. 在 HA 中前往 个人资料 → 安全 → 长期访问令牌

  2. 点击 创建令牌，命名为 nexus

  3. 将其作为 HA_TOKEN 粘贴到 .env 文件中

连接 MCP 客户端

启动 Nexus 后，打开 http://your-ha-ip:7123。设置页面会为每个客户端生成精确的命令或配置片段 — 只需复制并粘贴即可。

所有基于 SSE 的客户端连接地址为：

http://your-ha-ip:7123/mcp?token=YOUR_API_KEY

Claude Code CLI

claude mcp add nexus --transport sse "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY" --scope user

OpenAI Codex CLI

codex mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"

Gemini CLI

gemini mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"

VS Code

创建 .vscode/mcp.json：

{
  "servers": {
    "nexus": {
      "type": "sse",
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"
    }
  }
}

Cursor

粘贴到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "nexus": {
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
      "type": "sse"
    }
  }
}

Windsurf

粘贴到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "nexus": {
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
      "type": "sse"
    }
  }
}

Claude Desktop（独立运行，子进程模式）

粘贴到 %APPDATA%/Claude/claude_desktop_config.json (Windows) 或 ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)：

{
  "mcpServers": {
    "nexus": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/ha-nexus-agent",
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_ha_token_here"
      }
    }
  }
}

提示： 从 Nexus Web UI (http://your-ha-ip:7123) 复制确切的配置（包含您的真实路径和密钥）。

功能特性

  • 202 个 MCP 工具，涵盖 21 个类别

  • 实时 WebSocket — 实时订阅状态更改、事件和触发器

  • Git 版本控制 — 每次配置更改都会自动提交，支持即时回滚

  • YAML 验证 — 在写入任何配置文件前进行校验

  • 设置 Web UI — 为每个客户端自动生成可直接使用的 MCP 配置

  • HA 插件原生支持 — 从插件商店一键安装，无需手动设置令牌

  • API 密钥认证 — MCP 端点受保护，令牌通过 URL 查询参数传递

工具概览

类别

数量

示例

entities_*

17

list_entities, turn_on/off/toggle, bulk_control, set/get_entity_exposure (语音助手)

services_*

19

call_service, send_notification, set_light_color, camera_snapshot, camera_record, persistent_notification 创建/关闭

automations_*

21

list/trigger/enable/disable, get/set/delete_automation_config (完整 YAML CRUD), list/get_automation_traces (调试)，脚本和场景同理

blueprints_*

4

list, import (从 URL), delete, substitute (带输入参数实例化)

areas_*

8

list_areas, create_area, get_area_states, control_area

devices_*

4

list_devices, update_device (重命名/移动到区域/禁用), remove_device, list_devices_in_area

calendar_*

4

list_calendars, list_events, create_event, delete_event

todo_*

5

list_todo_lists, list_items, add_item, update_item, remove_item

helpers_*

11

set_input_boolean, set_input_number, start_timer, increment_counter

history_*

5

get_state_history, get_logbook, get_error_log

system_*

9

check_config, create_backup, restart_ha, list_integrations

dashboards_*

6

get_dashboard_config, add_card_to_view, add_view_to_dashboard

files_*

6

read_config_file, write_config_file, validate_yaml_content

git_*

11

git_commit_all, git_rollback_file, git_log, safe_write_with_checkpoint

ws_*

7

listen_state_changes, listen_events, subscribe_trigger

supervisor_*

20

插件的 list/install/start/stop/restart/update/uninstall, addon_logs, addon_options, backups (列表/创建/恢复/删除), core/host 信息 + 重启

hacs_*

7

HACS 仓库的 list/install/uninstall/update, 添加自定义仓库, 列出关键更新

Git 版本控制

Nexus 会保留您 HA 配置目录的 Git 历史记录。在进行任何高风险更改之前，请使用 git_safe_write_with_checkpoint — 它会先提交当前状态，然后再应用更改。如果出现问题，可以立即回滚。

git_init_config()                                    # run once
git_safe_write_with_checkpoint("automations.yaml", new_content)
git_rollback_file("automations.yaml")                # undo single file
git_rollback_to_commit("abc1234")                    # full rollback
git_log(limit=10)                                    # see history

环境变量

变量

必需

默认值

描述

HA_URL

是

http://homeassistant.local:8123

Home Assistant URL

HA_TOKEN

仅独立运行

—

长期访问令牌

SUPERVISOR_TOKEN

仅插件

自动注入

由 HA 自动设置

HA_CONFIG_PATH

用于 Git 工具

/config

HA 配置目录路径

NEXUS_API_KEY

否

自动生成

固定为特定的 API 密钥

NEXUS_PORT

否

7123

HTTP 服务器端口

Install Server
A
license - permissive license
B
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
4Releases (12mo)

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Fistacho/ha-nexus-agent'

If you have feedback or need assistance with the MCP directory API, please join our Discord server