Larnitech

Larnitech MCP

版本 1.3.3 Beta · 更新日志 · MIT 许可

一个 MCP 服务，可让 AI Agent 通过 API2 协议读取和控制 Larnitech 智能家居系统， 包括灯光、温控、百叶窗、传感器和计量仪表。

它附带一份有文档说明的设备类型参考，内容基于对真实控制器的实际测试， 因此 Agent 会查询组件的实际行为，而不是根据键名猜测。这一点比听起来 更重要：在这个平台上，向闸门写入 state: "closed" 会得到 success: true 的确认，却被悄悄忽略；而且有几种温控类型会丢弃任何双键写入中的一半内容。这些陷阱都有文档说明，每次写入前都会进行检查，并列在本 README 的安全须知部分中。

---

功能介绍

读取 — 开箱即用，除 API 密钥外无需配置。

工具	功能
list_objects	列出已配置的控制器（不会返回密钥）
check_connection	连接并授权，报告设备数量
list_devices	获取完整快照，可按区域／类型／名称筛选
get_device	按地址获取单个设备的状态

连续调用会共用一个已授权的连接：请求完成后，套接字会保持打开 4 分钟，因此一连串读取只需连接一次，而不是每次调用都重新连接。连接会在控制器自身的 5 分钟空闲超时之前关闭；如果控制器已断开连接，系统会自动替换连接，不会导致调用失败。

理解返回结果 — 状态因设备类型而异，偶尔也不是键值对。

工具	功能
get_docs()	所有已记录设备类型的概览
get_docs("AC")	单个类型的完整详情：状态键、枚举值、XML 属性、脚本字节布局和特殊情况
get_docs("bugs")	已确认供应商缺陷的编号登记表
get_docs("protocol")	API2 协议参考

响应会标记需要谨慎处理的状态：不透明的 hex 数据块、代替常规读数的 malfunction 故障代码、错过轮询周期的仪表返回的全为 null 的负载（这表示没有数据，而不是零），或者单独出现的 state: "undefined"，这是物理离线设备仍会作出的响应。

监视 — 非阻塞，适用于“按下开关并告诉我发生了什么变化”。

工具	功能
watch_start	开始监视；立即返回
watch_read	读取自上次读取以来的变化，按键显示 from／to
watch_stop / watch_list	停止单项监视／列出活动监视

监视会保持自己的连接，因此不会受控制器 5 分钟空闲超时的影响，也可以在长时间对话期间保持开启。

写入 — 默认关闭，分两阶段进行，绝不会只调用一个工具。

工具	功能
set_device	验证并预览更改，返回令牌 — 不会写入
confirm_set	执行更改，然后等待设备状态稳定并报告实际生效的内容

学习 — 发现的信息会保留到会话结束之后。

工具	写入位置
add_docs_note	相应设备类型自己的文档文件
add_preference	preferences.md，每次调用 get_docs 时都会提供

保存数据 — 快照比滚动记录更有价值。

工具	功能
save_snapshot	将一部分控制器数据保存为文件
list_snapshots	按控制器列出已保存的快照
read_snapshot	读取单个快照，以便与当前状态比较

文件保存在 data/<controller>/<date>_<time>_<comment>.txt 中，每个控制器各有一个文件夹；如果该安装已有一个存放图纸、配置和控制器备份的项目目录，也可以保存到你自己的文件夹中：

python -m larnitech_mcp data-dir "Home" "/projects/home/backups"

这样，快照就会与站点的其他文件放在一起，而不是存入单独的存储位置。list_snapshots 会查找这两种位置。

每个快照都是一个 JSON 信封，包含 object、saved_at、comment，以及位于 data 下的负载，因此文件会保留来源信息，而 read_snapshot 会返回解析后的结构，无需重新解析文本。数字仍是数字，null 仍是 null，这一点在这里很重要：区分“没有数据”和零，意味着能分辨仪表没有读数，还是读数为零。

说“保存当前状态”，Agent 就会将其保存到相应位置；说“和上周相比有变化吗”，它就有内容可以进行比较。

报告问题 — report_bug 会将你遇到的问题整理成可直接提交到此仓库的问题报告。它会撰写报告、移除标识信息（API 密钥、序列号、主机名、站点名称），并返回一个预填好的链接。系统不会发布任何内容：你可以打开链接，准确查看将要发布的内容，并使用自己的账户自行提交。任何人都不需要令牌。

---

要求

• Python 3.11+
• 你管理的 Larnitech 控制器，可通过 Larnitech 云或局域网访问

安装

pip install larnitech-mcp

建议使用虚拟环境，因为你需要将 Claude Code 指向该解释器的绝对路径：

python -m venv ~/.venvs/larnitech
~/.venvs/larnitech/bin/pip install larnitech-mcp     # Windows: Scripts\pip.exe

你的 API 密钥、偏好设置、已保存的快照，以及 Agent 记录的任何设备备注，都存放在软件包之外的 ~/.larnitech-mcp/ 中，因此升级不会影响这些内容。

若要在服务器本身上进行开发，请改为从克隆的仓库安装：

git clone https://github.com/mpopovych-thinkhome/larnitech-mcp.git
cd larnitech-mcp
pip install -e .

获取 API 密钥

这两个值都可以在你管理的安装环境中通过 Larnitech 自带的配置应用 LT_Setup 获取：

内容	在 LT_Setup 中的位置
API 密钥	Security → Show API key
序列号（云连接）	General
IP 地址（局域网连接）	General，或路由器的 DHCP 列表
WebSocket 端口（局域网，默认为 2041）	General → API → Websocket port

该密钥具有对安装环境的完整读写权限，请像对待密码一样妥善保管。

连接控制器

注册控制器，然后保存密钥：

python -m larnitech_mcp add "Home" cloud --serial YOUR_SERIAL
python -m larnitech_mcp auth "Home"

auth 会通过隐藏输入提示你输入密钥，并将密钥写入 ~/.larnitech-mcp/project_keys.json。这样密钥不会经过聊天记录，因此建议优先使用此方式，而不是使用 object_set_key 工具；后者虽然可用，但会将密钥留在会话日志中。

若要连接局域网内的控制器，而非通过云连接：

python -m larnitech_mcp add "Home" local --host 192.168.1.50

检查连接是否正常：

python -m larnitech_mcp test "Home"      # connect, authorize, count devices
python -m larnitech_mcp devices "Home"   # full snapshot, counts per type

添加到 Claude Code

将服务添加到 ~/.claude.json 顶层的 mcpServers 对象中，并使用虚拟环境中 Python 的绝对路径：

{
  "mcpServers": {
    "larnitech": {
      "command": "/home/you/.venvs/larnitech/bin/python",
      "args": ["-m", "larnitech_mcp", "serve"]
    }
  }
}

在 Windows 上，命令为 .exe，反斜杠需转义：

"command": "C:\\Users\\you\\.venvs\\larnitech\\Scripts\\python.exe"

必须将配置放在 ~/.claude.json 本身顶层的 mcpServers 键下；放在 ~/.claude/ 文件夹中的 .mcp.json 不会被读取。若要仅对某个项目启用，请将相同的配置块放在该项目根目录下的 .mcp.json 中。之后请完全重启 Claude Code；仅关闭窗口并不足够。

其他 MCP 客户端的配置方式也相同：该服务通过 python -m larnitech_mcp serve 使用标准输入输出运行。

---

安全模型

读取权限默认开放。写入权限默认关闭；需在终端中逐个控制器启用：

python -m larnitech_mcp allow-write "Home" on

我们刻意不提供用于启用写入权限的工具——Agent 无法自行授予写入权限，只能告诉你该运行哪条命令。

每次写入都分为两次调用。 set_device 会验证负载、读取当前状态，并返回预览和一个一次性令牌；它不会接触控制器。confirm_set(token) 会执行写入，等待设备状态稳定后，再报告实际生效的内容，包括 unrequested_changes——也就是控制器自行更改的任何内容。

**写入可以分步执行，**因为某些类型无法通过单个帧驱动：

[{"status": {"mode": "heat"}, "delay_after": 1.0},
 {"status": {"state": "on"}}]

同时发送 mode 和 state 会导致 state 丢失：模式更改后，控制器会重新评估通道，并覆盖随之发送的任何内容。vent（state + fan）也有同样的问题；切换通道之前清除 automation 也是如此。set_device 会拒绝这些组合形式，并告知你应使用的操作顺序。

**工具绝不会返回密钥，**错误消息也会对密钥进行遮蔽。

设备文档

larnitech_mcp/docs/device-types/ 中每种设备类型各有一个文件，另有一个索引，涵盖 API2 状态键、XML 属性、脚本端字节布局，以及通过现场测试确认的所有特性。旁边的 bugs.md 是已确认厂商错误的编号登记表，各类型文件会引用其中的条目。请通过 get_docs 阅读这些文档，而不是按路径读取——这样也能获取你在本地添加的内容。

Agent 通过 add_docs_note 记录的备注会写入 ~/.larnitech-mcp/docs/，而非已安装的软件包，因此升级后仍会保留。读取时优先使用你的副本；你未编辑的内容仍来自随软件包提供的文档。

这是一个持续完善的知识库，而非规范：条目会明确标注某项内容是已通过现场测试确认、已观察到但原因不明，还是仍然未知。欢迎纠正和补充——这是最有价值的贡献。

命令参考

命令	作用
add <name> cloud --serial S	注册云控制器
add <name> local --host H [--port P]	注册局域网控制器
auth <name>	保存其 API 密钥（隐藏式提示）
list	列出已配置的控制器及密钥状态
test <name>	连接、授权并统计设备数量
devices <name> [--full]	获取完整快照并解码
allow-write <name> on|off	启用或禁用写入
remove <name>	移除控制器及其密钥
serve	通过标准输入输出运行 MCP 服务

状态

Beta 版。读取、监视和写入功能均可用，并已在真实硬件上进行测试，但测试覆盖的安装环境有限。标注为未确认的设备类型确实尚未确认——请参阅 get_docs 的输出和各类型文件。

与 Larnitech 无关联，也未获其认可。

许可证

MIT

联系方式

Mykhailo Popovych

• Telegram：t.me/M_Popovych_ThinkHome
• 电话（WhatsApp）：+370 632 89 991，+380 99 333 99 96
• 电子邮件：[email protected]