Skip to main content
Glama

OpenHAB MCP Server

A Fast and Concise Model Context Protocol (MCP) server for OpenHAB (v5+).

This server exposes the entire OpenHAB REST API as a set of tools for AI models like Claude or VS Code assistants. It allows for complete control over Items, Things, Rules, Persistence, Semantic Tags, and more.

Prerequisites

  • Node.js (v18 or higher)

  • An OpenHAB API Token (Generate in User Profile -> API Tokens)

Related MCP server: hass-mcp-server

Configuration

The server requires two environment variables:

  • OPENHAB_URL: The URL of your OpenHAB instance (e.g., http://openhab:8080)

  • OPENHAB_API_TOKEN: Your generated long-lived API token.

Setup instructions

  1. Install dependencies:

    npm install
  2. Build the server:

    npm run build
  3. Test locally (Optional):

    OPENHAB_URL=http://openhab:8080 OPENHAB_API_TOKEN=your_token_here npm start

Client Integration

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "openhab": {
      "command": "node",
      "args": ["/path/to/oh-mcp/dist/index.js"],
      "env": {
        "OPENHAB_URL": "http://openhab:8080",
        "OPENHAB_API_TOKEN": "your_openhab_token_here"
      }
    }
  }
}

Antigravity

Add the following to your Antigravity MCP settings:

{
  "mcpServers": {
    "openhab": {
      "command": "node",
      "args": ["/path/to/oh-mcp/dist/index.js"],
      "env": {
        "OPENHAB_URL": "http://openhab:8080",
        "OPENHAB_API_TOKEN": "your_openhab_token_here"
      }
    }
  }
}

VS Code (Roo/Cline)

Add an MCP server entry to your VS Code workspace settings (open Settings (JSON) or create .vscode/settings.json):

{
  "servers": {
    "openhab": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "OPENHAB_URL": "http://openhab:8080",
        "OPENHAB_API_TOKEN": "your_openhab_token_here"
      }
    }
  }
}

Quick steps to run from VS Code:

  1. Install deps and build the project:

npm install
npm run build
  1. Start the server (Linux/macOS):

OPENHAB_URL=http://openhab:8080 OPENHAB_API_TOKEN=your_openhab_token_here npm start
  1. For iterative development, run TypeScript in watch mode and restart the server after builds (in two terminals):

npm run dev        # keeps tsc watching
npm start          # runs node dist/index.js (in a second terminal)
  1. Run as a VS Code Task (example .vscode/tasks.json):

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run OpenHAB MCP",
      "type": "shell",
      "command": "OPENHAB_URL=http://openhab:8080 OPENHAB_API_TOKEN=your_openhab_token_here npm start",
      "group": "build",
      "presentation": { "reveal": "always" }
    }
  ]
}

Note for Windows (PowerShell): set env vars before running:

$env:OPENHAB_URL = 'http://openhab:8080'; $env:OPENHAB_API_TOKEN = 'your_openhab_token_here'; npm start

Tips:

  • Use ${workspaceFolder}/dist/index.js in the args so the server is launched from your opened workspace.

  • Add the server config to Workspace settings (not User) if you share the repo with collaborators.

  • Use the npm: build task in the Command Palette (Tasks → Run Task) to compile before starting.


🛠 Available Tools

This server exposes over 80 tools for comprehensive OpenHAB management.

🚀 Smart & Advanced Tools

Tools designed to automate complex workflows and provide AI-friendly context.

  • get_system_summary: High-density overview of the entire system (rooms, items, things, health).

  • get_prompt_context: Condensed priming context for an AI agent.

  • get_schema: Minimal mapping of all items (name, type, label).

  • search_items: Fuzzy search for items by name, label, or location.

  • create_equipment_from_thing: Automatically creates an Equipment group and Point items from a Thing's channels.

  • explain_item_state: Forensic review of an item (state + history + linked hardware + affecting rules).

  • predictive_rule_generator: Generates a validated Javascript rule from natural language intent.

  • shadow_run: Simulates a sequence of commands and predicts resulting states without hardware impact.

  • generate_topology: Generates a Mermaid graph of the home's spatial/logical hierarchy.

  • analyze_system_health: Scans for hardware issues, connectivity drift, and low batteries.

  • audit_semantic_model: Structural audit to find loose items or missing equipment hierarchy.

  • bulk_item_remediation: Mass-update tags, categories, and groups for a list of items.

  • discover_automation_patterns: Correlation engine to suggest automations based on persistence history.

  • detect_rule_conflicts: Identifies potential race conditions or conflicting logic between rules.

  • standardize_naming_convention: Proposes a unified Location_Equipment_Point naming format.

  • optimize_persistence_strategy: Recommends optimal recording intervals to prevent database bloat.

  • sitemap_to_main_ui: Converts legacy .sitemap definitions to modern MainUI YAML.

  • optimize_mcp_focus: Locks the MCP to a specific Room or Group to save tokens and increase AI accuracy.

  • export_system_snapshot: Generates a portable JSON snapshot for rapid backup and restore.

  • get_mcp_health: Returns real-time health metrics (SSE status, cache hit rates, buffer size).

  • summarize_persistence_range: Returns statistical summary of historical data to save context tokens.

  • get_mcp_capabilities: Returns a list of currently active advanced capabilities.

  • simulate_system_state: Predicts command outcomes (including triggers) without affecting hardware.

  • generate_home_blueprint: Auto-generates a structured Markdown manual of your entire home model.

  • audit_system_safety: Proactive scanner for security items (Locks, Alarms) with safety check logic.

  • calculate_energy_insights: Aggregates energy/power data into a high-level consumption report.

  • get_semantic_path: Returns the full semantic path for an item (e.g., Lounge > Sofa > Light).

  • find_neighboring_equipment: AI-driven search for other devices in the same physical location.

  • schedule_command: Schedules a command for the future (e.g., "turn off in 10 minutes").

  • get_stale_items: Identifies sensors or items that haven't updated in a specified period.

  • test_transformation: Evaluate REGEX or JSONPATH patterns locally.

  • get_recent_logs: Real-time tail of the OpenHAB event stream (items, commands, things).

  • get_visual_chart: Generates ASCII sparkline charts for an item's recent history.

  • validate_rule_logic: Sanitizes scripts for syntax errors and safety (infinite loops/guards).

🔹 Items & State

  • get_items: List all items with advanced filters (tags, type, metadata).

  • get_item: Detailed definition and current state of an item.

  • send_command: Send a command (e.g., ON, 50, OFF) to an item.

  • update_state: Manually set an item's state.

  • create_or_update_item: Lifecycle management for items.

  • delete_item: Remove an item.

  • get_room_status: Summary of all items tagged in a specific room.

  • add_tag / remove_tag: Manage functional and semantic tags.

  • set_metadata / remove_metadata: Fine-grained configuration management.

🔹 Hardware & Connectivity

  • get_things: List all logical/physical Things.

  • get_thing: Detailed hardware configuration and UID mapping.

  • get_thing_status: Check if hardware is ONLINE, OFFLINE, etc.

  • update_thing_config: Modify hardware parameters.

  • enable_thing: Restart or disable a specific Thing.

  • create_thing / update_thing / delete_thing: Manage hardware lifecycle.

  • get_inbox: Review discovered devices waiting to be added.

  • approve_inbox_item: Promote a discovered device to a system Thing.

  • trigger_discovery_scan: Manually trigger a hardware scan for a specific binding (e.g., Hue, Sonos).

🔹 Automation & Rules

  • get_rules: List all rule definitions.

  • get_rule: Inspect triggers, conditions, and actions.

  • create_rule / update_rule / delete_rule: Rule lifecycle.

  • run_rule: Manually trigger an automation.

  • enable_rule: Toggle automation logic.

🔹 Persistence & Analysis

  • get_item_persistence_data: Fetch historical raw data points.

  • get_item_statistics: Calculate peaks, averages, and duty cycles over time.

  • store_item_persistence_data: Manually insert state history.

  • get_persistence_services: List storage backends (RRD4j, InfluxDB, etc.).

  • manage_link: List, create, or remove item-channel links, or configure a link profile. Write actions require the exact itemName and full channelUID (for example, binding:thing:channel); link accepts config, while configure accepts profile and optional profileConfig.

  • get_semantic_tags: Retrieve standard Location/Equipment/Point tags.

  • suggest_semantic_tags: AI-driven tagging suggestions based on item naming.

🔹 Media, Voice & Scenes

  • control_media: Context-aware controls (play, pause, next, volume) for any media item.

  • capture_scene: Save a snapshot of multiple item states as a Scene.

  • activate_scene: Restore a saved Scene state.

  • voice_say: Send text-to-speech to a specific speaker.

  • voice_interpret: Resolve natural language commands via OpenHAB's interpreter.

  • chat_with_habot: NLP interaction with the HABot interface.

  • get_voices / get_audio_sinks / get_audio_sources: Discover audio capabilities.

🔹 UI & System Maintenance

  • get_ui_components / get_ui_tiles: Access MainUI layout data.

  • generate_ui_widget: Create MainUI YAML for custom dashboard widgets.

  • get_system_info: CPU, Memory, Java version, and OS details.

  • get_loggers / set_logger_level: Monitor and change log verbosity on the fly.

  • get_addons / install_addon / uninstall_addon: Manage system extensions.

  • get_sitemaps: Access legacy sitemap UI definitions.

  • generate_system_boilerplate: Create Typescript interfaces for your entire home.

License

MIT

Release 1.4.1

This release (1.4.1) fixes HTTP 400 errors when creating item-channel links or applying link profiles, and raises minimum MCP SDK and Axios versions to patched releases. See CHANGELOG.md for full details.

Contributing

Contributions are welcome. Please follow the Conventional Commits specification for commit messages so changelogs and automation remain consistent.

  • Commit message format: type(scope): short description (e.g., fix(openhab-client): handle null response).

  • Common types: feat, fix, docs, style, refactor, perf, test, chore.

Example:

docs(readme): add contributing guidelines and conventional commits example

If you're submitting a change that affects behavior, include tests under src/__tests__/ when appropriate.

Available Tools

25 tools
analyze_homeA

Home-wide analysis. action: health (offline + battery), safety_audit, energy, stale_items, orphans (broken links), semantic_audit (returns structured SemanticIssue objects with issue type + safeFix suggestions — same logic as the OpenHAB MainUI model page), rule_conflicts, find_equipment (by room + type), voice_exposure (Google/Alexa mappings).

Inputs: action (required), days, roomName, equipmentType.

automationB

Automation generation and testing. action: generate_rule (from NL), discover_patterns (temporal correlation), shadow_run (dry-run preview), simulate (predict outcome + rule chains), validate_rule (JS syntax check).

Inputs: action (required), intent, script, command, +3 more.

control_mediaC

Control a media player equipment item. action: play, pause, next, previous, volume_up, volume_down.

Inputs: action (required), equipmentName (required).

diagnose_itemA

Item diagnostics. action: explain (forensic state + rules + history), topology (Mermaid home graph).

Inputs: action (required), itemName.

execute_batchA

Execute multiple commands in parallel. Use for "Goodnight", scene-like, or multi-device actions.

Inputs: commands (required).

generate_home_blueprintA

Full room-by-room Markdown guide of the home. Use for layout exploration or when a user explicitly asks for a home overview — NOT as a first step (use initial_discovery instead).

Inputs: no named parameters.

get_system_summaryA

High-density snapshot of the OpenHAB system: items, things, rooms, health.

Inputs: no named parameters.

initial_discoveryA

One-shot bootstrap: returns a compact guidance context with a room-grouped quick-reference of every item (name, type, live state). Call ONCE on first contact. Do NOT also call generate_home_blueprint or get_system_summary — this covers all discovery needs.

Inputs: no named parameters.

manage_itemB

Modify items. action: create_or_update, delete, update_state, add_tag, remove_tag, set_metadata, remove_metadata. WARNING: Do NOT use create_or_update for semantic model fixes (parentage, hierarchy). Use remediate action=semantic_fix instead. create_or_update safely merges existing groupNames and tags on update, but semantic relationships (hasLocation, isPointOf, isPartOf) must go through semantic_fix. WARNING: Do NOT use create_or_update for semantic model fixes (parentage, hierarchy). Use remediate action=semantic_fix instead. create_or_update safely merges existing groupNames and tags on update, but semantic relationships (hasLocation, isPointOf, isPartOf) must go through semantic_fix.

Inputs: action (required), itemName (required), tag, state, +4 more.

manage_logsB

OpenHAB log access. Logs are on the remote OpenHAB server — ask the user for the path and call set_folder first. action: set_folder, recent, historical, search.

Inputs: action (required), lines, query, search, +3 more.

manage_persistenceC

Persistence data operations. action: services (list), get_data, store_data, statistics, summarize.

Inputs: action (required), time, state, endtime, +3 more.

manage_ruleC

Manage automation rules. action: create, update, delete, enable, disable, run.

Inputs: action (required), ruleUID, ruleData.

manage_sceneC

Named scene management. action: capture (save current item states), activate (restore a saved scene).

Inputs: name (required), action (required), itemNames.

manage_systemD

System config, loggers, voice/audio, and binding scans. action: system_info, services, service_config_get, service_config_update, logger_list, logger_set, transformations, templates, trigger_scan, voice_say, voice_interpret, voices, audio_sinks, audio_sources, habot.

Inputs: action (required), text, level, config, +5 more.

manage_thingC

Manage things. action: create, update, delete, enable, disable, configure.

Inputs: action (required), force, config, thingUID, +1 more.

manage_uiD

UI, add-ons, sitemaps, semantic tags, and discovery inbox. action: addons, install_addon, uninstall_addon, sitemaps, sitemap_to_main_ui, ui_components, ui_tiles, generate_widget, semantic_tags, create_tag, update_tag, delete_tag, inbox_list, inbox_approve, inbox_ignore, inbox_unignore.

Inputs: action (required), label, tagId, addonId, +6 more.

mcp_statusB

MCP server metadata. action: health (SSE/cache metrics), capabilities, prompt_context (AI priming context for this home).

Inputs: action (required).

query_itemsC

Read item data. action: all (list with optional filters), get (by name), multi (batch by names), search (fuzzy text), master_search (across items+things+rules), room_inventory, semantic_path, neighbors, schema.

Inputs: action (required), tags, type, query, +5 more.

query_rulesB

Read automation rules. action: all (list all), get (by UID).

Inputs: action (required), ruleUID.

query_thingsC

Read thing data. action: all (list all), get (by UID), status (status info).

Inputs: action (required), thingUID.

remediateB

Bulk remediation and generation. action: bulk_update (batch tags/groups), create_equipment (auto-provision from thing), suggest_tags, standardize_naming, optimize_persistence, export_snapshot, boilerplate (TS types). semantic_fix: safely fix ONE item's semantic parent without touching other fields or groupNames — uses targeted REST endpoints (metadata only + additive group). semantic_fix_all: run full audit and auto-apply all safely fixable issues (dryRun=true for preview).

Inputs: action (required), addTag, dryRun, updates, +6 more.

resolve_itemA

PRIMARY item finder. Converts natural-language intent ("kitchen light", "front door sensor") into ranked matches with exact names, types, rooms, and live states. Call this BEFORE any other search.

Inputs: query (required).

schedule_commandA

Schedule a command to run after a delay (e.g. "turn off in 20 minutes").

Inputs: command (required), delayMs (required), itemName (required).

send_commandC

Send a command (ON, OFF, numeric value, etc.) to a single item.

Inputs: command (required), itemName (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 25 tools

    Disambiguation3/5

    Several tools overlap in practice: query_items vs resolve_item, initial_discovery vs get_system_summary vs generate_home_blueprint, and analyze_home vs diagnose_item vs remediate semantic fixes. The descriptions try hard to disambiguate with explicit 'PRIMARY' and 'do NOT use' warnings, which helps but also signals genuine boundary confusion.

    Naming Consistency4/5

    Most names follow a predictable snake_case verb_noun or manage_/query_ pattern (manage_item, query_things, send_command, execute_batch). Minor deviations like remediate, automation, initial_discovery, and mcp_status are readable but break the pattern slightly.

    Tool Count3/5

    At 25 tools, the surface is at the heavy end, and many tools are large action multiplexers with 5-15 actions each. The domain is broad, but overlapping discovery, query, and analysis tools make the count feel excessive rather than tightly scoped.

    Completeness5/5

    Coverage is broad and lifecycle-complete across items, things, rules, links, scenes, persistence, logs, UI, system config, media control, and automation generation. No obvious core OpenHAB operation appears missing.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers