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)

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

2. Start the server (Linux/macOS):

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

3. 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)

4. 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.).

🔹 Links & Semantic Model

• get_links: View relationships between Items and Hardware Channels.

• link_item_to_channel: Bind an item to a specific channel.

• unlink_item_from_channel: Remove a binding.

• configure_link_profile: Apply profiles like system:follow or transform:JS to a link.

• 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.3.2

This release (1.3.2) contains performance optimisations across several hot-path methods and a correctness fix for detectRuleConflicts. 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.