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.