homeclaw

HomeClaw exposes your HomeKit accessories through a command-line tool, a stdio MCP server, and plugins for Claude Code and OpenClaw. It runs as a lightweight macOS menu bar app.

Screenshots

Why HomeClaw?

Apple HomeKit has no public API, no CLI, and no way to integrate with AI assistants or automation pipelines. HomeClaw bridges that gap with a Mac Catalyst app that talks to HomeKit on your behalf and exposes a clean API surface.

• Ask Claude or OpenClaw to "turn off all the lights" or "set the thermostat to 72"
• Script your smart home from the terminal
• Build automations that go beyond what the Home app offers
• Search and control devices by name, room, category, or semantic type

Architecture

Claude Code --> Plugin (.claude-plugin/) --> stdio MCP server (Node.js) --+
Claude Desktop --> stdio MCP server (Node.js) ----------------------------+
OpenClaw --> Plugin (openclaw/) --> homeclaw-cli --------------------------+
                                                                          v
                                               Unix socket (JSON newline-delimited)
                                                                          |
                                               HomeClaw (Mac Catalyst app)
                                                 +-- HomeKitManager (direct, in-process)
                                                 +-- SocketServer (for CLI/MCP clients)
                                                 +-- macOSBridge.bundle (NSStatusItem menu bar)

Single-process design. Apple's HMHomeManager requires a UIKit/Catalyst app with the HomeKit entitlement. By making the entire app Catalyst, HomeKit access is direct (no IPC), signing is unified (single archive), and App Store submission is clean. The macOSBridge plugin bundle provides the native macOS menu bar via NSStatusItem.

Native MCP for Hermes

HomeClaw must be running before connecting. In Settings → Integrations, enable Streamable HTTP MCP. This persistent setting is off by default; turning it off stops the HTTP listener without disabling existing stdio or Unix-socket clients. When enabled, the Catalyst app owns a loopback-only Streamable HTTP endpoint:

http://127.0.0.1:9090/mcp

Loopback binding prevents remote network access; no bearer token or shell launch is required. Readiness is available at http://127.0.0.1:9090/healthz. In Hermes, add:

mcp_servers:
  homeclaw:
    url: http://127.0.0.1:9090/mcp
    timeout: 120
    connect_timeout: 30

The stdio MCP server remains supported for Claude Desktop, Claude Code, and OpenClaw. Use the existing npm run build:mcp and stdio setup when a client cannot use native HTTP.

Native transport development checks

swift test covers the CLI package only. To build and execute the full native Catalyst HomeClawTests suite on macOS 26 or later:

npm install
node scripts/check-mcp-schema-parity.mjs
xcodegen generate
bash scripts/test-catalyst.sh

The test script saves the xcodebuild log and .xcresult under .build/catalyst-test-evidence/ and fails on empty or skipped test results. For a repeat run, set CATALYST_EVIDENCE_DIR to a fresh directory. Unit-test hosting suppresses live HomeKit, socket, and menu-bar startup; these tests are not proof of HomeKit provisioning or real accessory access.

lib/schemas.js is the canonical tool schema. The Swift descriptors are readable JSON and CI compares every descriptor against the Node export and the XCTest fixture. After an intentional schema edit, regenerate both reviewed copies with node scripts/check-mcp-schema-parity.mjs --write, then inspect their diff. The HTTP read-only allowlist remains separate and deny-by-default; adding a tool to the canonical schema does not expose it over HTTP.

Install

Marketing site with screenshots and full pitch: homeclaw.omarknows.app.

Mac App Store (Recommended)

HomeClaw is live on the Mac App Store:

1. Open in the Mac App Store and install
2. Launch HomeClaw -- grant HomeKit access when prompted
3. The menu bar icon appears. Click it to see your connected homes.

App Store builds are fully signed and notarized, so HomeKit works without any developer account setup.

TestFlight Beta

Want early access to in-flight builds before they ship to the App Store?

1. Join the TestFlight Beta
2. Install HomeClaw from TestFlight
3. Launch the app -- grant HomeKit access when prompted

TestFlight builds are signed the same way as App Store builds, so HomeKit works out of the box. You'll get new features (like the automations work in v1.0.1) before they hit the App Store.

After installing

Set up your AI integrations:

• Claude Desktop -- one-click install from Settings > Integrations, or add the MCP server config manually
• Claude Code -- install the plugin from GitHub
• OpenClaw -- one-click install from Settings > Integrations, or set up manually

Build from Source

Prerequisites

• macOS 26 (Tahoe) or later
• Xcode 26+ with Swift 6.2
• XcodeGen: brew install xcodegen
• Node.js 20+ (for the MCP server wrapper)
• Apple Developer account with HomeKit capability enabled

Why is a developer account required? Apple does not provide a public HomeKit API for macOS. The only way to access HomeKit is through HMHomeManager, which requires the com.apple.developer.homekit entitlement and a provisioning profile that covers your Mac's hardware UDID. Apple restricts this entitlement to development signing and App Store distribution -- it cannot be included in Developer ID (notarized) builds. This means every Mac that runs HomeClaw must be registered as a development device in your Apple Developer portal, and the app must be built with your team's signing identity. There is no way around this; it's an Apple platform restriction, not a HomeClaw limitation.

Setup

git clone https://github.com/omarshahine/HomeClaw.git
cd HomeClaw

# Configure your Apple Developer Team ID (one-time setup)
echo "HOMEKIT_TEAM_ID=YOUR_TEAM_ID" > .env.local

# Install Node.js dependencies
npm install

# Build everything and install
scripts/build.sh --release --install

Find your Team ID at developer.apple.com/account under Membership Details.

Launch from /Applications or: open "/Applications/HomeClaw.app"

On first launch, grant HomeKit access when prompted. The menu bar icon appears -- click it to see your connected homes.

Note: Apple restricts the HomeKit entitlement to development signing and App Store distribution. Developer ID builds cannot access HomeKit. See Why Development Signing? for details.

MCP Tools

The stdio MCP server wraps homeclaw-cli and exposes these tools:

Tool	Description
homekit_status	Check bridge connectivity and accessory count
homekit_accessories	List, get details, search, or control accessories
homekit_rooms	List rooms and their accessories
homekit_scenes	List, get details, trigger, import, or delete scenes
homekit_device_map	LLM-optimized device map with semantic types and aliases
homekit_manage	Manage home structure: rename accessories/rooms, create/remove rooms and zones, manage zone membership
homekit_automations	Manage automations: list, create button-press triggers (single/double/long), link to scenes, enable/disable
homekit_events	Query recent HomeKit events (characteristic changes, scene triggers, control actions)
homekit_webhook	Manage webhook configuration: setup (configure + auto-test), test, reset circuit breaker, status
homekit_config	View or update configuration (set active home, filtering)

Connecting an MCP Client

Any MCP-compatible client can connect via the stdio server, which wraps homeclaw-cli and requires no authentication (the HomeClaw app must be running for the socket). Add this to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "homeclaw": {
      "command": "node",
      "args": ["/Applications/HomeClaw.app/Contents/Resources/mcp-server.js"]
    }
  }
}

The mcp-server.js is bundled inside the app. You can also use the Integrations tab in Settings to install this automatically.

CLI

The homeclaw-cli command-line tool communicates directly over the Unix domain socket. All read commands support --json for machine-readable output. Day-to-day commands also accept --home <name-or-uuid> to target a specific HomeKit home without changing the configured default (config --default-home).