OpenHAB MCP Server

Name: OpenHAB MCP Server
Author: tdeckers

本地服务

github.com/tdeckers其他2518 周前更新

代码仓库

关于 OpenHAB MCP Server

OpenHAB MCP 服务是连接真实 openHAB 实例的 MCP 服务器，通过 REST API 管理智能家居系统。它面向希望使用 Claude 或 Cline 以自然语言管理 openHAB 的用户，并支持可自托管的容器部署。

主要功能

01管理 Items、Things、Rules 和 Scripts
02支持 Item 与 Thing 状态及配置的读写
03提供 item-channel 链接的查询与清理工具
04支持 stdio、Streamable HTTP 与 SSE 传输
05提供预构建的容器镜像

适用场景

01通过 AI 助手查询与控制智能家居设备
02检查 Thing 状态与固件更新情况
03按需运行或维护 openHAB 规则与脚本

MCP 相关

该项目是 MCP 服务器，向 MCP 客户端暴露 openHAB 的 Items、Things、Rules、Scripts 和 Links 等操作工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 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）服务。

概述

本项目提供了一个 MCP 服务的实现，通过 openHAB 的 REST API 连接到真实的 openHAB 实例。它使 Claude 和 Cline 等 AI 助手能够与你的 openHAB 智能家居系统交互。

该服务提供对 openHAB 核心组件的全面访问：

Items

列出、获取、创建、更新和删除 item
更新 item 状态

Things

列出所有 thing
获取、创建、更新和删除 thing
更新 thing 配置
获取 thing 配置状态
设置 thing 启用/禁用状态
获取 thing 状态和固件信息
获取可用的固件更新

Rules

列出、获取、创建、更新和删除 rule
更新 rule 脚本操作
按需运行 rule

Scripts

列出、获取、创建、更新和删除 script

在 VSCode 中连接到 Claude 或 Cline 后，你可以使用自然语言控制和管理你的 openHAB 系统，让家庭自动化更易于使用、更直观。

要求

Python 3.7+

快速开始（预构建镜像）

官方镜像已发布到 GitHub Container Registry（ghcr.io/tdeckers/openhab-mcp）。拉取此镜像是让 MCP 服务运行起来最快的方式。

默认情况下，服务使用 stdio 进行 MCP 通信。对于远程 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，但示例将其映射到主机上的端口 8081，以避免与现有的 OpenHAB 安装冲突。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 之前，请确保在 shell 中设置了 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 桌面应用
对于 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 + 远程）

这些检查使用本地构建的容器，验证 list_items 工具在 stdio、Streamable HTTP 和 SSE 模式下均能正常工作。它们假设存在一个可访问的 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 - 分页列出 openHAB thing，支持可选的 UID 和标签过滤
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 item-channel 链接，可选按 channel UID 或 item 名称过滤
get_link - 获取特定的 openHAB item-channel 链接
create_or_update_link - 创建或更新 openHAB item-channel 链接
delete_link - 删除特定的 openHAB item-channel 链接
get_orphan_links - 获取孤立的 openHAB item-channel 链接（指向不存在的 channel 的链接）
purge_orphan_links - 移除所有孤立的 openHAB item-channel 链接
delete_all_links_for_object - 删除特定 item 或 thing 的所有 openHAB 链接

MCP 资源

该服务提供以下资源：

openhab://items - openHAB 系统中所有 item 的列表
openhab://items/{item_name} - 按名称获取特定 item

示例 Item 结构

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

开发

出于开发目的，请参阅 DEVELOPER.md 文件，了解基于 Podman 的开发工作流的更多信息。

说明

此实现通过 REST API 连接到真实的 openHAB 实例。在生产环境中使用时，你可能希望增强以下方面：

更全面的错误处理和日志记录
额外的身份验证和安全功能
更复杂的缓存机制
支持更多 openHAB 功能（规则、thing 等）

许可证

MIT

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。