Larnitech

Larnitech MCP

バージョン 1.3.3 Beta · 変更履歴 · MIT ライセンス

AI エージェントが API2 プロトコル経由で Larnitech のスマートホーム設備（照明、空調、ブラインド、センサー、メーター）を読み取り、制御できる MCP サーバーです。

実際のコントローラーでの実機テストをもとに作成した、デバイスタイプの詳細なリファレンスが付属しています。エージェントはキー名から推測するのではなく、各ウィジェットの実際の動作を参照できます。これは思われている以上に重要です。このプラットフォームでは、ゲートに state: "closed" を書き込むと success: true で受け付けられたあと、何も起こらないまま無視されます。また、いくつかの空調タイプでは、2 つのキーを書き込むと片方が反映されません。こうした落とし穴は文書化され、書き込みのたびに確認されるほか、この README の安全に関するセクションにも記載されています。

---

できること

読み取り — オープンで、API キー以外の設定は不要です。

ツール	できること
list_objects	設定済みのコントローラーを一覧表示します（キーは返しません）
check_connection	接続して認証し、デバイス数を報告します
list_devices	完全なスナップショットを取得します。エリア／タイプ／名前で絞り込めます
get_device	アドレスを指定して、1 台のデバイスの状態を取得します

連続する呼び出しでは、認証済みの接続を共有します。リクエスト後もソケットは4分間開いたままなので、複数回まとめて読み取る場合、呼び出しごとに接続するのではなく、1回の接続で済みます。コントローラー独自の5分間のアイドルタイムアウトより前に接続を終了します。また、コントローラーがすでに切断した接続は、呼び出しを失敗させずに再接続します。

取得した内容の理解 — 状態はデバイスのタイプごとに異なり、ときにはキーと値の形式ではありません。

ツール	できること
get_docs()	ドキュメントに記載されたすべてのデバイスタイプの概要
get_docs("AC")	1つのタイプの詳細：状態キー、列挙値、XML 属性、スクリプトのバイト配置、特記事項
get_docs("bugs")	確認済みのベンダーバグを番号付きで登録した一覧
get_docs("protocol")	API2 プロトコルリファレンス

応答では、注意が必要な状態にフラグが付けられます。不透明な hex blob、通常の読み取り値の代わりに返される障害コード malfunction、ポーリングサイクルを逃したメーターからの null のみのペイロード（これはゼロではなく、データなしを意味します）、または単独の state: "undefined"（物理的にオフラインのデバイスが応答するときの状態です）などです。

監視 — ノンブロッキングで、「スイッチを押して、何が動いたか教えて」といった用途に使えます。

ツール	できること
watch_start	監視を開始し、すぐに戻ります
watch_read	前回の読み取り以降に変化した内容を、キーごとの from／to で取得します
watch_stop / watch_list	監視を1つ停止／稼働中の監視を一覧表示します

監視は独自の接続を維持するため、コントローラーの5分間のアイドルタイムアウトを超えて継続でき、長い会話の間も開いたままにできます。

書き込み — デフォルトでは無効で、2段階方式です。ツールを1回呼び出すだけで書き込むことは決してありません。

ツール	できること
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 はどちらの形式も見つけます。

各スナップショットは、object、saved_at、comment と、data の下にあるペイロードを含む JSON エンベロープです。そのため、ファイルとともに出所情報が保持され、read_snapshot は再解析が必要なテキストではなく、解析済みの構造を返します。数値は数値のまま、null は null のまま保持されます。ここではこれが重要です。「データなし」とゼロを区別することは、メーターが静かな状態なのか、読み取り値がゼロなのかの違いだからです。

「現在の状態を保存して」と頼めば、エージェントがそこにファイルを保存します。「先週から変わった？」と頼めば、比較できるデータが用意されています。

レポート — report_bug は、遭遇した問題をこのリポジトリに提出できる形のイシューにまとめます。レポートを作成し、識別情報（API キー、シリアル番号、ホスト名、サイト名）を取り除いて、入力済みのリンクを返します。投稿は行われません。リンクを開き、公開される内容を正確に確認してから、ご自身のアカウントで送信してください。誰もトークンを必要としません。

---

要件

• Python 3.11+
• 管理者としてアクセスでき、Larnitech クラウド経由または LAN 上で接続できる Larnitech コントローラー

インストール

pip install larnitech-mcp

Claude Code からそのインタープリターの絶対パスを指定するため、仮想環境の使用をおすすめします。

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

API キー、設定、保存したスナップショット、エージェントが記録したデバイスのメモはすべて、パッケージの外にある ~/.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 アドレス（LAN 接続）	General、またはルーターの DHCP テーブル
WebSocket ポート（LAN、デフォルト 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 ツールよりも、この方法をおすすめします。

クラウド経由ではなく、LAN 上のコントローラーに接続する場合：

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 に追加する

仮想環境の Python の絶対パスを指定して、~/.claude.json のトップレベルにある mcpServers オブジェクトにサーバーを追加します。

{
  "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 を使い、stdio 経由で実行されます。

---

安全性モデル

読み取りは常に可能です。書き込みは、コントローラーごとに、ターミナルから有効にするまで無効です。

python -m larnitech_mcp allow-write "Home" on

意図的に、この操作を行うツールは用意されていません。エージェントは書き込みアクセスを自分で許可できず、コマンドを案内することしかできません。

書き込みは毎回、2 回の呼び出しで行います。 set_device はペイロードを検証し、現在の状態を読み取って、プレビューと使い捨てトークンを返します。コントローラーには一切アクセスしません。confirm_set(token) は書き込みを実行し、デバイスが落ち着くまで待ってから、実際に反映された内容を報告します。これには、コントローラーが独自に変更した内容である unrequested_changes も含まれます。

書き込みを複数段階で行うこともできます。 種類によっては、1 つのフレームでは制御できないためです。

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

mode と state を同時に送信すると、state は失われます。モード変更後にコントローラーがチャンネルを再評価し、その後に受信した値を上書きするためです。同じことは、vent（state + fan）や、チャンネルをオフにする前に automation をクリアする場合にも当てはまります。set_device は、これらを組み合わせた形式を拒否し、代わりに使用する手順を案内します。

ツールからキーが返されることはありません。 また、エラーメッセージ内のキーはマスキングされます。

デバイスのドキュメント

larnitech_mcp/docs/device-types/ には、デバイスタイプごとに1つのファイルとインデックスがあり、API2 のステータスキー、XML 属性、スクリプト側のバイト配置、ライブテストで確認されたすべての特記事項を記載しています。その隣にある bugs.md は、各タイプのファイルから参照される、確認済みのベンダーのバグを番号付きでまとめたものです。パスを指定するのではなく、get_docs から読み込んでください。ローカルで追加した内容も反映されます。

エージェントが add_docs_note で記録したメモは、インストール済みパッケージではなく ~/.larnitech-mcp/docs/ に保存されるため、アップグレード後も残ります。読み込み時には、お使いのコピーが優先されます。編集していない内容は、引き続き同梱のファイルから読み込まれます。

これは仕様書ではなく、作業中のナレッジベースです。各項目では、ライブ環境で確認済みか、観察されているものの説明されていないか、まだ不明なのかを明記しています。修正や追加も歓迎します。ここで最も価値のある貢献です。

コマンドリファレンス

コマンド	効果
add <name> cloud --serial S	クラウドコントローラーを登録します
add <name> local --host H [--port P]	LAN コントローラーを登録します
auth <name>	API キーを保存します（入力は非表示）
list	設定済みコントローラーとキーの有無を表示します
test <name>	接続、認証、デバイス数のカウントを行います
devices <name> [--full]	デコード済みの完全なスナップショットを表示します
allow-write <name> on|off	書き込みを有効または無効にします
remove <name>	コントローラーとそのキーを削除します
serve	stdio で MCP サーバーを実行します

ステータス

ベータ版です。読み取り、監視、書き込みはすべて動作し、実機でテスト済みですが、限られた数の設置環境でのみテストされています。未確認と記載されているデバイスタイプは、実際に未確認です。get_docs の出力とタイプごとのファイルを参照してください。

Larnitech とは提携しておらず、Larnitech からの推奨も受けていません。

ライセンス

MIT

連絡先

Mykhailo Popovych

• Telegram: t.me/M_Popovych_ThinkHome
• 電話（WhatsApp）：+370 632 89 991, +380 99 333 99 96
• メール：[email protected]