OpenHAB MCP Server

A MCP (Model Context Protocol) server that interacts with a real openHAB instance.

Overview

This project provides an implementation of an MCP server that connects to a real openHAB instance via its REST API. It enables AI assistants like Claude and Cline to interact with your openHAB smart home system.

The server provides comprehensive access to openHAB's core components:

Items

List, get, create, update, and delete items
Update item states

Things

List all things
Get, create, update, and delete things
Update thing configurations
Get thing configuration status
Set thing enabled/disabled status
Get thing status and firmware information
Get available firmware updates

Rules

List, get, create, update, and delete rules
Update rule script actions
Run rules on demand

Scripts

List, get, create, update, and delete scripts

When connected to Claude or Cline in VSCode, you can use natural language to control and manage your openHAB system, making home automation more accessible and intuitive.

Requirements

Python 3.7+

Quick Start (prebuilt image)

The official image is published to the GitHub Container Registry (ghcr.io/tdeckers/openhab-mcp). Pulling this image is the fastest way to get the MCP server running.

(Optional for private registries) Authenticate with GHCR:
```
podman login ghcr.io
# or: docker login ghcr.io
```

Run the container with Podman (add -e OPENHAB_USERNAME=... and -e OPENHAB_PASSWORD=... if your OpenHAB instance requires basic authentication):

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


 Using Docker instead?
 ```bash
 docker run -d --rm -p 8081:8080 \
   -e OPENHAB_URL=http://your-openhab-host:8080 \
   -e OPENHAB_API_TOKEN=your-api-token \
   --name openhab-mcp \
   ghcr.io/tdeckers/openhab-mcp:latest

Stop the container when you are done:

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

The container exposes port 8080 internally, but the examples map it to port 8081 on the host to avoid conflicts with an existing OpenHAB installation.

Optional: Build and run a custom image

If you need to modify the code, build and tag the image locally instead:

Build the image:

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

Run your custom image:

make docker-run
# or directly:
podman run -d --rm -p 8081:8080 \
  -e OPENHAB_URL=http://your-openhab-host:8080 \
  -e OPENHAB_API_TOKEN=your-api-token \
  --name openhab-mcp \
  openhab-mcp

Ensure the OPENHAB_URL, OPENHAB_API_TOKEN, and optional OPENHAB_USERNAME/OPENHAB_PASSWORD variables are set in your shell before invoking make docker-run.

Stop the custom container:

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

Using with Claude and Cline in VSCode

You can connect this OpenHAB MCP server to Claude or Cline in VSCode to interact with your OpenHAB instance through AI assistants.

Prerequisites

For Claude: Claude Desktop app installed
For Cline: Cline VSCode extension installed

Configuration for Claude Desktop

Run the container using the steps in "Quick Start" (published image) or "Optional: Build and run a custom image".
Create a configuration file for Claude Desktop:

Save the following as claude_desktop_config.json in your Claude Desktop configuration directory:

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:8080",
        "-e",
        "OPENHAB_URL=http://your-openhab-host:8080",
        "-e",
        "OPENHAB_API_TOKEN=your-api-token",
        "--name",
        "openhab-mcp",
        "ghcr.io/tdeckers/openhab-mcp:latest"
      ]
    }
  ]
}

Configuration for Cline in VSCode

Run the container using the steps in "Quick Start" (published image) or "Optional: Build and run a custom image".
Create a configuration file for Cline:

Save the following as mcp.json in your Cline configuration directory:

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

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

Restart and Verify

After creating the configuration file, restart Claude Desktop or VSCode
Open a new conversation with Claude or Cline
You should now be able to interact with your OpenHAB instance through the AI assistant

Example prompt to test the connection:

Can you list all the items in my OpenHAB system?

If configured correctly, Claude/Cline will use the MCP server to fetch and display your OpenHAB items.

MCP Tools

The server provides the following tools:

Item Management

list_items - Paginated list of openHAB items with optional tag, type, name, and label filters
get_item - Get a specific openHAB item by name
create_item - Create a new openHAB item
update_item - Update an existing openHAB item
delete_item - Delete an openHAB item
update_item_state - Update just the state of an openHAB item

Thing Management

list_things - Paginated list of openHAB things with optional UID and label filters
get_thing - Get a specific openHAB thing by UID
create_thing - Create a new openHAB thing
update_thing - Update an existing openHAB thing
delete_thing - Delete an openHAB thing
update_thing_config - Update an openHAB thing's configuration
get_thing_config_status - Get openHAB thing configuration status
set_thing_enabled - Set the enabled status of an openHAB thing
get_thing_status - Get openHAB thing status
get_thing_firmware_status - Get openHAB thing firmware status
get_available_firmwares - Get available firmwares for an openHAB thing

Rule Management

list_rules - List all openHAB rules, optionally filtered by tag
get_rule - Get a specific openHAB rule by UID
create_rule - Create a new openHAB rule
update_rule - Update an existing openHAB rule with partial updates
update_rule_script_action - Update a script action in an openHAB rule
delete_rule - Delete an openHAB rule
run_rule_now - Run an openHAB rule immediately

Script Management

list_scripts - List all openHAB scripts (rules with tag 'Script' and no trigger)
get_script - Get a specific openHAB script by ID
create_script - Create a new openHAB script
update_script - Update an existing openHAB script
delete_script - Delete an openHAB script

Link Management

list_links - List all openHAB item-channel links, optionally filtered by channel UID or item name
get_link - Get a specific openHAB item-channel link
create_or_update_link - Create or update an openHAB item-channel link
delete_link - Delete a specific openHAB item-channel link
get_orphan_links - Get orphaned openHAB item-channel links (links to non-existent channels)
purge_orphan_links - Remove all orphaned openHAB item-channel links
delete_all_links_for_object - Delete all openHAB links for a specific item or thing

MCP Resources

The server provides the following resources:

openhab://items - List of all items in the openHAB system
openhab://items/{item_name} - Get a specific item by name

Sample Item Structure

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

Development

For development purposes, please refer to the DEVELOPER.md file for more information on the Podman-based development workflow.

Notes

This implementation connects to a real openHAB instance via its REST API. For production use, you might want to enhance it with:

More comprehensive error handling and logging
Additional authentication and security features
More sophisticated caching mechanisms
Support for more openHAB features (rules, things, etc.)

License

MIT