OpenHAB MCP Server

Name: OpenHAB MCP Server
Author: tdeckers

ローカル

github.com/tdeckersその他2518 週間前に更新

リポジトリ

OpenHAB MCP Server について

OpenHAB MCP サーバーは、REST API を通じて実際の openHAB インスタンスに接続する MCP サーバーです。Claude や Cline などのアシスタントから自然言語でスマートホームを管理したい利用者を想定しており、セルフホスト可能なコンテナとして提供されます。

主な機能

01アイテム、Thing、ルール、スクリプトの管理
02アイテムと Thing の状態および設定の読み書き
03アイテムとチャネルのリンクの一覧表示と整理
04stdio、Streamable HTTP、SSE のトランスポートに対応
05ビルド済みコンテナイメージの提供

活用シーン

01AI アシスタントからのスマートホーム機器の確認と操作
02Thing の状態とファームウェア更新の確認
03ルールやスクリプトのオンデマンド実行と保守

MCP 対応

本プロジェクトは MCP サーバーであり、openHAB のアイテム、Thing、ルール、スクリプト、リンクの操作をツールとして MCP クライアントに公開します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "openhab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "\\"
      ]
    }
  }
}

起動コマンドdocker run -i --rm '\'

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

oci\stdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

OpenHAB MCP サーバー

実際の openHAB インスタンスと連携する MCP（Model Context Protocol）サーバーです。

概要

このプロジェクトは、REST API 経由で実際の openHAB インスタンスに接続する MCP サーバーの実装を提供します。Claude や Cline などの AI アシスタントが、openHAB スマートホームシステムと連携できるようにします。

このサーバーは、openHAB の中核コンポーネントに包括的にアクセスできます。

アイテム

アイテムの一覧表示、取得、作成、更新、削除
アイテムの状態の更新

Thing

すべての Thing の一覧表示
Thing の取得、作成、更新、削除
Thing の設定の更新
Thing の設定ステータスの取得
Thing の有効／無効状態の設定
Thing のステータスとファームウェア情報の取得
利用可能なファームウェア更新の取得

ルール

ルールの一覧表示、取得、作成、更新、削除
ルールのスクリプトアクションの更新
必要に応じたルールの実行

スクリプト

スクリプトの一覧表示、取得、作成、更新、削除

VSCode の Claude または Cline に接続すると、自然言語を使って openHAB システムを制御、管理できるため、ホームオートメーションをより手軽で直感的に利用できます。

要件

Python 3.7+

クイックスタート（ビルド済みイメージ）

公式イメージは GitHub Container Registry（ghcr.io/tdeckers/openhab-mcp）で公開されています。このイメージを取得するのが、MCP サーバーを最も手早く起動する方法です。

デフォルトでは、サーバーは MCP に stdio を使用します。リモート HTTP クライアントの場合は、MCP_MODE=remote を設定すると、同じコンテナから http://HOST:PORT/mcp の Streamable HTTP と http://HOST:PORT/sse の SSE の両方を公開できます。以下のコンテナの例ではリモートモードを使用しています。stdio を使う場合は、MCP_MODE とポートマッピングを省略してください。Streamable HTTP は、ステートフルクライアント用の Mcp-Session-Id などのセッションヘッダーをサポートしています。

（プライベートレジストリの場合は任意）GHCR で認証します。
```
podman login ghcr.io
# or: docker login ghcr.io
```

Podman でコンテナを実行します（OpenHAB インスタンスで基本認証が必要な場合は、-e OPENHAB_USERNAME=... と -e OPENHAB_PASSWORD=... を追加します）。

podman run -d --rm -p 8081:8000 \
  -e MCP_MODE=remote \
  -e OPENHAB_URL=http://your-openhab-host:8080 \
  -e OPENHAB_API_TOKEN=your-api-token \
  --name openhab-mcp \
  ghcr.io/tdeckers/openhab-mcp:latest

Docker を使用する場合はこちらです。

docker run -d --rm -p 8081:8000 \
  -e MCP_MODE=remote \
  -e OPENHAB_URL=http://your-openhab-host:8080 \
  -e OPENHAB_API_TOKEN=your-api-token \
  --name openhab-mcp \
  ghcr.io/tdeckers/openhab-mcp:latest

使用後はコンテナを停止します。

podman stop openhab-mcp
# or: docker stop openhab-mcp

MCP_MODE=remote で実行すると、コンテナは内部でポート 8000 をリッスンします。ただし、既存の OpenHAB インストールとの競合を避けるため、以下の例ではホストのポート 8081 にマッピングしています。Streamable HTTP クライアントは http://HOST:PORT/mcp に接続し、SSE クライアントは http://HOST:PORT/sse に接続します。

オプション：カスタムイメージのビルドと実行

コードを変更する必要がある場合は、代わりにイメージをローカルでビルドしてタグ付けします。

イメージをビルドします。

make docker-build
# or directly: podman build -t openhab-mcp .

カスタムイメージを実行します。
```
make docker-run
# or directly:
podman run -d --rm -p 8081:8000 \
  -e MCP_MODE=remote \
  -e OPENHAB_URL=http://your-openhab-host:8080 \
  -e OPENHAB_API_TOKEN=your-api-token \
  --name openhab-mcp \
  openhab-mcp
```
make docker-run を実行する前に、シェルで OPENHAB_URL、OPENHAB_API_TOKEN、および任意の OPENHAB_USERNAME／OPENHAB_PASSWORD 変数が設定されていることを確認してください。

カスタムコンテナを停止します。

make docker-stop
# or directly: podman stop openhab-mcp

VSCode の Claude および Cline での使用

この OpenHAB MCP サーバーを VSCode の Claude または Cline に接続すると、AI アシスタントを通じて OpenHAB インスタンスと連携できます。

前提条件

Claude の場合：Claude Desktop アプリがインストールされていること
Cline の場合：Cline VSCode 拡張機能がインストールされていること

Claude Desktop の設定

「クイックスタート」（公開イメージ）または「オプション：カスタムイメージのビルドと実行」の手順に従ってコンテナを実行します。
Claude Desktop 用の設定ファイルを作成します。

以下を Claude Desktop の設定ディレクトリにある claude_desktop_config.json として保存します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcp_servers": [
    {
      "name": "openhab-mcp",
      "command": "podman",
      "args": [
        "run",
        "-d",
        "-p",
        "8081:8000",
        "-e",
        "MCP_MODE=remote",
        "-e",
        "OPENHAB_URL=http://your-openhab-host:8080",
        "-e",
        "OPENHAB_API_TOKEN=your-api-token",
        "--name",
        "openhab-mcp",
        "ghcr.io/tdeckers/openhab-mcp:latest"
      ]
    }
  ]
}

VSCode の Cline の設定

「クイックスタート」（公開イメージ）または「オプション：カスタムイメージのビルドと実行」の手順に従ってコンテナを実行します。
Cline 用の設定ファイルを作成します。

以下を Cline の設定ディレクトリにある mcp.json として保存します。

macOS/Linux：~/.cursor/mcp.json
Windows：%USERPROFILE%\.cursor\mcp.json

{
  "mcp_servers": [
    {
      "name": "openhab-mcp",
      "command": "podman",
      "args": [
        "run",
        "-d",
        "-p",
        "8081:8000",
        "-e",
        "MCP_MODE=remote",
        "-e",
        "OPENHAB_URL=http://your-openhab-host:8080",
        "-e",
        "OPENHAB_API_TOKEN=your-api-token",
        "--name",
        "openhab-mcp",
        "ghcr.io/tdeckers/openhab-mcp:latest"
      ]
    }
  ]
}

再起動と確認

設定ファイルを作成したら、Claude Desktop または VSCode を再起動します
Claude または Cline で新しい会話を開きます
AI アシスタントを通じて、OpenHAB インスタンスとやり取りできるようになります

接続をテストするプロンプトの例：

Can you list all the items in my OpenHAB system?

正しく設定されていれば、Claude/Cline は MCP サーバーを使用して OpenHAB のアイテムを取得し、表示します。

トランスポートエンドポイント（Streamable HTTP と SSE）

リモートモード： MCP_MODE=remote を設定し、http://HOST:PORT/mcp（Streamable HTTP）または http://HOST:PORT/sse（SSE）に接続します

Streamable HTTP クライアントが /sse に POST した場合、サーバーは 405 Method Not Allowed を返す必要があります。これは /sse が SSE の GET／サブスクライブリクエストのみを受け付けるためです（使用している FastMCP のバージョンで確認してください）。

トランスポートのスモークテスト

デプロイ後、以下の簡単な確認を行います。

Streamable HTTP
- MCP_MODE=remote が設定されていることを確認します。
- /mcp に POST して初期化します（クライアントライブラリが自動的に処理します）。
- 手動で確認します（通常、GET は 405 を返し、POST は成功します。使用している FastMCP のバージョンで確認してください）。
```
curl -i http://HOST:PORT/mcp
```
SSE
- MCP_MODE=remote が設定されていることを確認します。
- SSE エンドポイントは、サブスクリプション用に /sse で GET を受け付けます。
- 手動で確認します（SSE ストリームが返されることを想定しています）。
```
curl -i http://HOST:PORT/sse
```

ローカル統合テスト計画（stdio とリモート）

この確認では、ローカルでビルドしたコンテナーを使い、stdio、Streamable HTTP、SSE モードで list_items ツールが動作することを検証します。接続可能な openHAB インスタンスがあることを前提としています（ローカル環境の場合は make dev-env を使用してください）。

イメージをビルドします。
```
make docker-build
```
openHAB を起動します（すでにインスタンスがある場合は省略可能です）。
```
make dev-env
```

stdio： サーバーをローカルで実行し、stdio 経由で list_items を呼び出します。

OPENHAB_URL=http://localhost:18080 \
OPENHAB_API_TOKEN=your-api-token \
uv run python scripts/mcp_client_stdio_list_items.py

リモート： コンテナーをリモートモードで実行します。

podman run -d --rm -p 8081:8000 \
  -e MCP_MODE=remote \
  -e OPENHAB_URL=http://localhost:18080 \
  -e OPENHAB_API_TOKEN=your-api-token \
  --name openhab-mcp \
  openhab-mcp

Streamable HTTP： /mcp 経由で list_items を呼び出します。
```
uv run python scripts/mcp_client_streamable_list_items.py
```
SSE： /sse 経由で list_items を呼び出します。
```
uv run python scripts/mcp_client_sse_list_items.py
```
コンテナーを停止します。
```
podman stop openhab-mcp
```

MCP ツール

サーバーは以下のツールを提供します。

アイテム管理

list_items - タグ、タイプ、名前、ラベルで任意にフィルタリングできる、openHAB アイテムのページ分割された一覧
get_item - 名前で特定の openHAB アイテムを取得
create_item - 新しい openHAB アイテムを作成
update_item - 既存の openHAB アイテムを更新
delete_item - openHAB アイテムを削除
update_item_state - openHAB アイテムの状態のみを更新

Thing 管理

list_things - UID とラベルで任意にフィルタリングできる、openHAB Thing のページ分割された一覧
get_thing - UID で特定の openHAB Thing を取得
create_thing - 新しい openHAB Thing を作成
update_thing - 既存の openHAB Thing を更新
delete_thing - openHAB Thing を削除
update_thing_config - openHAB Thing の設定を更新
get_thing_config_status - openHAB Thing の設定ステータスを取得
set_thing_enabled - openHAB Thing の有効状態を設定
get_thing_status - openHAB Thing のステータスを取得
get_thing_firmware_status - openHAB Thing のファームウェアステータスを取得
get_available_firmwares - openHAB Thing で利用可能なファームウェアを取得

ルール管理

list_rules - すべての openHAB ルールを一覧表示し、タグで絞り込むこともできます
get_rule - UID で特定の openHAB ルールを取得
create_rule - 新しい openHAB ルールを作成
update_rule - 部分更新で既存の openHAB ルールを更新
update_rule_script_action - openHAB ルール内のスクリプトアクションを更新
delete_rule - openHAB ルールを削除
run_rule_now - openHAB ルールをただちに実行

スクリプト管理

list_scripts - すべての openHAB スクリプトを一覧表示（タグが 'Script' で、トリガーがないルール）
get_script - ID で特定の openHAB スクリプトを取得
create_script - 新しい openHAB スクリプトを作成
update_script - 既存の openHAB スクリプトを更新
delete_script - openHAB スクリプトを削除

リンク管理

list_links - すべての openHAB アイテムとチャネルのリンクを一覧表示します。チャネル UID またはアイテム名で絞り込むこともできます
get_link - 特定の openHAB アイテムとチャネルのリンクを取得します
create_or_update_link - openHAB アイテムとチャネルのリンクを作成または更新します
delete_link - 特定の openHAB アイテムとチャネルのリンクを削除します
get_orphan_links - 孤立した openHAB アイテムとチャネルのリンク（存在しないチャネルへのリンク）を取得します
purge_orphan_links - 孤立した openHAB アイテムとチャネルのリンクをすべて削除します
delete_all_links_for_object - 特定のアイテムまたは Thing の openHAB リンクをすべて削除します

MCP リソース

サーバーは次のリソースを提供します。

openhab://items - openHAB システム内のすべてのアイテムの一覧
openhab://items/{item_name} - 名前を指定して特定のアイテムを取得します

アイテムの構造例

{
  "name": "LivingRoom_Light",
  "type": "Switch",
  "label": "Living Room Light",
  "state": "OFF",
  "tags": ["Lighting", "LivingRoom"],
  "groups": ["gLights", "gLivingRoom"]
}

開発

開発については、Podman ベースの開発ワークフローの詳細が記載された DEVELOPER.md ファイルを参照してください。

注意事項

この実装は、REST API を介して実際の openHAB インスタンスに接続します。本番環境で使用する場合は、次の機能を追加するとよいでしょう。

より包括的なエラー処理とロギング
追加の認証およびセキュリティ機能
より高度なキャッシュ機構
より多くの openHAB 機能（ルール、Thing など）のサポート

ライセンス

MIT

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。