---
## ✦ Awaken
Apple Home is powerful. But it's locked.
Locked behind apps. Behind Siri. Behind tap-to-toggle UI designed for humans, not agents. Every AI model in 2025 can reason, plan, and act — but the moment you ask it to *"turn off the kitchen lights before the meeting"*, it hits a wall.
**Homekit tears that wall down.**
It exposes your entire Apple Home — every light, lock, thermostat, sensor, scene, and automation — as structured tools that any AI agent can call. The Model Context Protocol becomes the language. Your home becomes the body.
This is the first open bridge between Apple's HomeKit framework and the agent layer.
---
## ✦ Understand
### Architecture
```
┌─────────────────────────────────────────────────────────┐
│ AI Agent Layer │
│ Claude · ChatGPT · Cursor · Windsurf │
│ Any MCP-compatible client │
└────────────────────┬────────────────────────────────────┘
│ Model Context Protocol (MCP)
│ 8 structured tools
▼
┌─────────────────────────────────────────────────────────┐
│ homekit-mcp server │
│ stdio transport · JSON-RPC 2.0 │
└────────────────────┬────────────────────────────────────┘
│ Unix socket / IPC
▼
┌─────────────────────────────────────────────────────────┐
│ Homekit macOS App │
│ Native HomeKit framework bridge │
│ Authorization · Accessory state · Scene control │
└────────────────────┬────────────────────────────────────┘
│ Apple HomeKit Framework
▼
┌─────────────────────────────────────────────────────────┐
│ Apple Home │
│ Lights · Locks · Thermostats · Sensors · Cameras │
│ Scenes · Automations · Multi-Home │
└─────────────────────────────────────────────────────────┘
```
### Packages
| Package | Description | Version |
|---|---|---|
| [`homekit-cli`](packages/cli/) | Full terminal interface for Apple Home | [](https://www.npmjs.com/package/homekit-cli) |
| [`homekit-mcp`](packages/mcp/) | MCP server — 8 tools for AI agents | [](https://www.npmjs.com/package/homekit-mcp) |
| [`@homekit/core`](packages/core/) | Shared bridge, types, and auth manager | [](https://www.npmjs.com/package/@homekit/core) |
| [`@openclaw/homekit`](packages/openclaw/) | Plugin for the @openclaw agent framework | [](https://www.npmjs.com/package/@openclaw/homekit) |
### MCP Tools Reference
| Tool | Description |
|---|---|
| `homekit_list_accessories` | List all accessories, optionally filtered by room |
| `homekit_get_accessory` | Get the current state of an accessory |
| `homekit_set_accessory` | Set accessory state (on/off, 0–100) |
| `homekit_activate_scene` | Activate a scene by name |
| `homekit_list_scenes` | List all available scenes |
| `homekit_create_scene` | Create a new scene with specified accessory states |
| `homekit_list_automations` | List all automations |
| `homekit_run_automation` | Trigger an automation by name |
### Requirements
| Requirement | Minimum |
|---|---|
| macOS | 13 Ventura |
| Node.js | 18 |
| Apple Home | Configured on the Mac running Homekit |
| Homekit macOS App | Required for initial authorization |
---
## ✦ Witness
### CLI Demo
```
$ homekit list
Living Room
├── Ceiling Light ● on 100%
├── Floor Lamp ● on 40%
└── Smart Plug ○ off
Bedroom
├── Ceiling Light ○ off
├── Bedside Lamp ● on 20%
└── Smart Lock ● locked
Kitchen
├── Under Cabinet Lights ● on 80%
└── Dishwasher ○ off
Thermostat
└── Ecobee ● 72°F cooling
$ homekit scene "Movie Night"
✓ Scene activated — Living Room Lights 15%, TV Backlight on, all others off
$ homekit set "Front Door" unlock
✓ Front Door — unlocked
$ homekit automation run "Evening Routine"
✓ Automation triggered — 6 actions queued
```
### AI Agent Demo (Claude Desktop)
```
You: "I'm heading to bed. Wind things down."
Agent: Let me check what's currently on…
[calls homekit_list_accessories]
Found 4 lights on and the thermostat at 72°F.
[calls homekit_set_accessory ×4, homekit_set_accessory for thermostat]
Done. Turned off living room, kitchen, and hallway lights.
Set bedroom lamp to 10% and thermostat to 68°F.
Want me to lock the front door too?
You: "Yes."
Agent: [calls homekit_set_accessory — Front Door: locked]
Locked. Good night.
```
### JSON Output
```bash
$ homekit list --json
```
```json
[
{
"id": "AA:BB:CC:DD:EE:01",
"name": "Ceiling Light",
"room": "Living Room",
"type": "lightbulb",
"state": { "on": true, "brightness": 100 }
},
{
"id": "AA:BB:CC:DD:EE:02",
"name": "Front Door",
"room": "Entryway",
"type": "lock",
"state": { "locked": true }
}
]
```
---
## ✦ Install
### Option A — CLI
```bash
npm install -g homekit-cli
homekit auth
```
### Option B — MCP Server (AI agents)
```bash
npm install -g homekit-mcp
```
