MCP AI Bridge
Control your Homey Pro with any AI assistant. Claude, ChatGPT, Gemini, Copilot, Cursor or Mistral. Just ask in plain language.
Talk to your Homey like you talk to a person. “Turn off the lights.” “Is the door still open?” “Set the heating to 21.” “Build me a flow for the porch light at sunset.” MCP AI Bridge lets your favorite AI assistant control your Homey Pro directly, in any language you speak. It runs locally on your Homey, works with every major assistant through the open MCP standard, and you stay in full control. Over 150 actions, your own custom AI commands in the flow editor, no extra cloud.
Links
App Store: MCP AI Bridge | Homey
Test version: MCP AI Bridge | Homey- Support and feedback: right here in this topic
What it is
Your Homey already runs your home. Now you can just talk to it.
MCP AI Bridge turns your Homey Pro into something any modern AI assistant can talk to directly. No middleman cloud, no separate integration for each assistant. The app runs a local Model Context Protocol (MCP) server on your Homey, and any MCP-compatible AI connects straight to it over your own network.
Once it is connected you stop digging through menus and just say what you want. The assistant reads the state of your home and changes it for you, in plain language, in any language you speak to it.
MCP is the open standard that Anthropic, OpenAI and Google are building their assistants around. Because the bridge speaks that standard, it is not tied to one vendor. The same Homey endpoint works in Claude, ChatGPT, Gemini, Cursor, Windsurf and more. 
Why this MCP app
There is more than one way to reach Homey from the outside. Here is why this one is the one to install.
Works with every assistant, not one. It speaks the open Model Context Protocol, so the same endpoint works in Claude, ChatGPT, Gemini, Cursor, Windsurf and any other MCP client. No lock-in.
Covers the whole Homey, not just switches. Over 150 actions across devices, zones, flows, advanced flows, logic, energy, insights, alarms, notifications, apps, dashboards and system.
You build your own AI commands. Expose custom tools to the assistant in the flow editor and send real answers back using live device values. The AI asks, your flow replies.
Local first. The AI connects to your Homey’s own address on your network. Nothing is routed through an extra cloud, and your home data is not handed to a third party.
Real security, not an afterthought. Four permission levels per key, an access switch to pause or limit everything in one click, a tool blocklist, guardrail rules, rate limits, and a security log with source IPs.
Each assistant only sees what it may use. The tool list is cut down to the permission of the key it connected with, so a read-only assistant is not even shown the tools it would be refused.
You can see what it does. Every action is auditable, with a diagnostics tab, broken flow detection and a live connections view. Argument values are never logged.
Open standard, full coverage, your own commands, local, and locked down by choice.
Just ask
Lights and climate
- “Turn off all the lights downstairs.”
- “Dim the living room to 30 percent.”
- “Set the bedroom to 19 degrees tonight.”
Check on things
- “Is the garage door still open?”
- “Which devices have a low battery?”
- “Anything offline right now?”
Energy and history
- “What used the most power this week?”
- “Average power use over the last 7 days?”
Automations
- “Make a flow that turns on the porch light at sunset.”
- “Set the heating to 21 tomorrow at 8 in the morning.”
- “Watch the front door and tell me when it opens.”
Housekeeping
- “Did anything fail in the last hour?”
- “Restart the Hue app.”
- “Are any of my flows broken?”
You talk normally. The assistant works out which devices and capabilities you mean and does it.
What it can reach
The bridge exposes your whole Homey through one clean interface:
Devices and every capability they have- Zones and rooms
Basic flows and Advanced Flows, including creating and editing them
Moods
Logic variables
Alarms and the alarm clock- Energy, live and historical
Insights, with one-number summaries
Notifications
Homey’s own dashboards, including building them
Installed apps, including enable, disable, restart and settings
Users and presence
System info, memory, storage and reboot
Over 150 actions in total, so the assistant can both understand the state of your home and act on it.
How it works
Under the hood it is a standard MCP server speaking JSON-RPC over local HTTP, using the StreamableHTTP transport from the MCP spec. Because it follows the open standard, the same endpoint works across clients.
Prefer to script against it? There is a plain REST shortcut at POST /tools/{name} and a full OpenAPI 3.1 spec at GET /openapi.json, so it drops right into tools like n8n, Make, or your own code.
Everything stays on your network. The AI connects to your Homey’s local address. No extra cloud in the path.
Connect your AI
Open the app settings and you get a connect wizard with a tab per client. Pick your assistant, copy the generated config, paste it in, done. The wizard fills in your Homey’s own address, adds the Authorization header when you have set an API key, and can merge the entry into a config file you already have instead of replacing it.
Every method it offers is below, so you can see what you are in for before installing.
Local clients, straight over your network
These connect from your own machine to your Homey’s address. No tunnel, no public URL, no subscription tier.
Claude Desktop: claude_desktop_config.json, via Settings, Developer, Edit Config
{
"mcpServers": {
"homey": {
"type": "http",
"url": "http://<homey-ip>:52199/mcp"
}
}
}
Claude Code: one command in your terminal
claude mcp add homey --transport http "http://<homey-ip>:52199/mcp"
Cursor and Windsurf: the same mcpServers block in mcp.json, then restart the editor.
Gemini: the regular Gemini app cannot add an MCP server yet, so use the CLI. Google replaced gemini-cli with antigravity-cli, and the two want a different key, which is why the wizard generates both.
Antigravity CLI, in ~/.gemini/antigravity-cli/mcp_config.json:
{
"mcpServers": {
"homey": {
"serverUrl": "http://<homey-ip>:52199/mcp"
}
}
}
Gemini CLI (older), in ~/.gemini/settings.json:
{
"mcpServers": {
"homey": {
"httpUrl": "http://<homey-ip>:52199/mcp"
}
}
}
GitHub Copilot in VS Code (agent mode), in .vscode/mcp.json. Note it uses servers, not mcpServers:
{
"servers": {
"homey": {
"type": "http",
"url": "http://<homey-ip>:52199/mcp"
}
}
}
Mistral Vibe, the CLI coding agent. Its own command writes the config for you:
vibe mcp add homey --url "http://<homey-ip>:52199/mcp" --transport streamable-http
Or put it in config.toml yourself, per project in .vibe/config.toml or for everything in ~/.vibe/config.toml. Note that this one is TOML with an array of tables, not a JSON map like the others:
[[mcp_servers]]
name = "homey"
transport = "streamable-http"
url = "http://<homey-ip>:52199/mcp"
Vibe cannot do OAuth yet, so if you reach your Homey from outside, give it your API key in a header rather than the consent page.
Older clients without native HTTP. Every local tab also has an mcp-remote variant, which needs Node.js on your computer:
{
"mcpServers": {
"homey": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://<homey-ip>:52199/mcp", "--allow-http"]
}
}
}
With an API key set, every client sends it as a header. The wizard fills in a YOUR_API_KEY placeholder for you to replace:
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
Cloud clients, which need a public address
ChatGPT and the Claude web app run on the internet, so they cannot reach a local address. For these you need your bridge publicly reachable over HTTPS, through a reverse proxy or a tunnel, plus an API key set on the Security tab. Then add a custom connector pointing at your public /mcp URL, with the key as the Authorization header.
Two things worth knowing before you go down that road:
- ChatGPT: write-capable custom MCP connectors are limited to Business, Enterprise and Edu. Plus and Pro get read-only, which still covers the roughly 80 read tools here but no control.
- Claude web or app: custom connectors are available on Free, Pro, Max, Team and Enterprise. Free is limited to one custom connector, which is exactly what you need here, and there is no read-only restriction.
If you do expose it, use the app’s own remote access (see below) rather than forwarding a port.
Build your own AI commands with flow cards
This is where it gets fun. The app ships flow cards so your AI and your flows work together both ways, not just the AI reaching into Homey.
Give the AI its own command
- Trigger: “An AI agent calls a custom tool.” The assistant calls a tool you define, your flow runs whatever logic you want, and you reply with “Return a response to the AI agent” using live device values and flow tokens. The AI asks, your flow answers.
See and react to what the AI does
- Trigger: “The AI controls a device.” Fires whenever the assistant changes a device, with the name, capability and value as tokens. Perfect for a quick “AI just set the thermostat to 19” notification.
Catch problems early
- Trigger: “A flow becomes broken.” Know the moment an automation breaks, for example after you removed a device.
- Trigger: “An AI tool call fails.” Know when the assistant hits an error.
- Trigger: “A security event occurs.” Get the source IP and reason when someone is denied or tries to connect without a key.
- Condition: “There is a broken flow.” Use it in a daily check flow.
Give the AI memory from your flows
- Action: “Remember a value for the AI.” A flow writes context the assistant can recall later.
- Condition: “A remembered value is.” A flow reads that memory back.
You are not limited to the built in tools. You design your own AI commands in the flow editor.
Real world examples
A custom AI tool that answers with live data
- Trigger: An AI agent calls a custom tool.
- Action: Return a response to the AI agent, using a flow token like the current power usage.
Now you can ask “how much power am I using right now” and the assistant gets the real number back from your flow.
Let the AI know nobody is home
- When everyone leaves, your presence flow runs “Remember a value for the AI”, key
nobody_home, valuetrue. - Later you ask the assistant to do something, and it can check that context first.
Get told when a flow breaks
- Trigger: A flow becomes broken.
- Action: send yourself a notification with the flow name.
You stay in control
The bridge is local first and locked down by choice.
Four permission levels, per key. Give each assistant its own API key at exactly the level it needs:
| Level | May do | May not |
|---|---|---|
| Read only | See everything | Change anything |
| Control only | Switch and set devices, start a flow, activate a mood, set a variable, send a notification | Rename, move between zones, change settings, create, overwrite or delete anything |
| Control and change | All of the above, plus editing flows, dashboards, moods and settings | Delete devices, uninstall apps, reboot, wipe stored data |
| Full | Everything |
Control only is the one to hand a voice assistant. It operates your house and leaves the way your house is set up alone.
Access mode switch. One control over the whole bridge, regardless of which keys exist: full, control and change, control only, read only, or off. Pause the AI or keep it read only while you are away, in one click.
The tool list follows the key. An assistant is only shown the tools its permission actually allows, and is told which level it is on. It says “this connection is not permitted to do that” instead of pretending your Homey cannot do it, and it does not waste a turn discovering each refusal.
And the rest:
Tool blocklist. Disable specific risky tools entirely, like deleting devices or rebooting Homey, even for a full key.
Guardrail rules. Block a tool or a capability outright, optionally only in a time window or on certain days. Enforced regardless of the key.
Confirmation on irreversible actions, on clients that can show a prompt.
IP whitelist and rate limits, with a separate tighter limit for destructive actions.
Security log. Every denied or unauthorized attempt is recorded with its source IP, right in the settings.
Active connections view. See who is connected, from which IP, and for how long.- The dashboard never leaves your network. It has no login of its own, so it is refused on the HTTPS port even with remote access on. Not a setting you can get wrong, it is fixed in the app. You can also switch it off on your own network entirely, which keeps everything you built.
By default, with nothing configured, it stays open on your trusted local network, the same as before. The controls are there when you want them.
Reaching it from outside your network (optional)
Off by default, and it stays off unless you turn it on. When you do, the bridge speaks OAuth 2.1 with PKCE, so a remote client goes through a consent page where you pick that connection’s permission and enter your API key. There is a global ceiling that caps every remote connection, whatever it was granted, and connectors can be revoked from the settings. Remote access refuses to switch on at all until you have set an API key.
The Remote tab carries the full step by step: how the chain fits together, three routes from your router to the connector in Claude or ChatGPT, which port goes where, how to test it before you connect anything, and what to check when it does not work.
If you do not need it, leave it alone. Everything above works on your own network without it.
Personal Access Token (optional)
Most tools work without one. A Personal Access Token is needed for two things the app’s own API token is not allowed to do:
- Creating, editing, deleting and starting flows. Tick the
homey.flowscope when you create the token at my.homey.app, Settings, API. - Homey’s own dashboards. These need the Dashboard scope, and here is the catch: that scope is not offered as a checkbox on the API key screen. It is not a firmware or version thing, it simply is not in the list. The only token that carries it is one created with the top entry Homey, which grants full access to everything. Worth deciding on purpose: take it if you want your assistant to build dashboards, and leave it if you do not.
The Status tab shows what your saved token can do and which scope it is still missing.
See what is happening
Twelve tabs, and each one says what it is for rather than assuming you built the thing.
Status lists every address the bridge answers on in one place, with its real state: your local address, HTTPS, the public address when remote access is on, and the dashboard. Underneath it, how many tools, connected assistants, schedules, watched devices, webhooks and keys you have.
Connection is step one, all of it about your own network: where your Homey is, the optional token for writing flows, and a tab per assistant with the config to copy.
Security has the four permission levels, the access switch, the blocklist, the guardrails and the security log, with a line on each saying what it does and how the layers stack.
Commands is seventy-eight example sentences in thirteen groups, tap to copy. Deliberately weighted towards the things people do not think to ask: have a flow explained back in plain language, find apps used in no flow at all, find devices that drew power all night.
Dashboard builds one for you in a click, lists the ones you have with which is served at /dashboard, and holds the prompt to hand your assistant if you want a custom one.
Memory, Planning and Events show what the assistant remembered, scheduled and is watching, each with example sentences to fill it, because on a fresh install they are empty and that used to look broken.
Diagnostics is every action with its result and how long it took, plus broken flow detection. Bug report makes a document you can paste into this topic, with everything needed to help and never a key or a token.
Argument values are never logged, so nothing sensitive leaks into the history.
Works with
Claude (Desktop, Code, mobile), ChatGPT, Google Gemini, GitHub Copilot, Cursor, Windsurf, Mistral Vibe, and any other MCP client. The text to speech and LED ring tools work on Homey Pro (Early 2019) and older models.
Get it
- Install from the App Store: MCP AI Bridge | Homey
- Or try the latest test build: MCP AI Bridge | Homey
- Open the app settings and run the connect wizard.
- Paste the config into your assistant and start talking to your home.
Questions, ideas and bug reports are very welcome in this topic. If the app makes your home a little easier to live with, a reply or a thumbs up helps other people find it. 
Changelog
v4.10.1 Mistral Vibe in the connect wizard, asked for in the app store.
Its config is the odd one out, TOML with an array of tables
where every other client takes a JSON map, so the tab saves you
the evening. Vibe cannot do OAuth yet, so from outside your
network you give it your API key in a header.
v4.10.0 Five things the dashboard was missing. Camera tiles, proxied by
the app so the page never holds a Homey token. Conditional cards
and rows that appear only when a condition holds. A list of your
dashboards in the settings, with which one is served and buttons
to open, promote or delete. A button that creates three moods,
all off, evening and leaving, per room that has lamps. And a
switch to stop serving the dashboard on your network while
keeping everything you built; the refusal from outside your
house is not a setting and has not changed.
v4.9.2 The settings page, gone through tab by tab, because most of it
assumed you had built the thing. Status lists every address the
bridge answers on with its real state. Security explains the
three settings that had none. The example commands went from
seventeen to seventy-eight. Memory, Planning and Events say why
they are empty and how to fill them. The remote guide grew from
six sections to fifteen. Two fixes: checking an Advanced Flow
reported it valid without looking at its references at all, and
a registry the app could not read counted as an empty one, which
reported perfectly good cards as missing.
v4.9.1 One bug report instead of two. The page and your assistant built
different documents, each missing what the other had. Also: a
stray POST to the dashboard is a plain not-found rather than a
failed login in your security log, the check interval really has
its five second minimum, the session list no longer hands out
ids that can close somebody else's connection, a flow named
after a built-in tool no longer replaces it, and a guardrail
naming a capability with a capital letter now fires.
v4.9.0 A full security audit. Four ways to get more access than you
were given are closed, including naming a script card under a
different field name and sending a structured argument as text,
which also walked past rules like never unlock the door. The
dashboard is local-network-only again: 4.8.0's HTTPS port would
have published it, and the token that operates your devices with
it. Remote access refuses to start without an API key. A
read-only key no longer receives a flow's card arguments or a
device's settings, which is where scripts and passwords live.
v4.8.0 The bridge can serve HTTPS itself, so the last hop from your
proxy stops being plain HTTP with your API key in the clear. A
certificate that does not load costs you HTTPS, never the
bridge. Plus a Connected apps list: every cloud assistant you
approved, with its permission, and a way to revoke it. Replacing
your API key revokes nothing, which is why that list exists.
v4.7.0 Your assistant is only shown the tools its key may use, and is
told which permission it is on, so it says this connection is
not allowed instead of pretending your Homey cannot do it. Four
tools that answered a bare failure now name what they could not
find. And a correction to 4.6.0: the Dashboard scope is not
offered when you create a token, only the top-level Homey scope
carries it.
v4.6.0 A fourth permission level, Control only. It switches devices,
starts flows, activates moods and sends notifications, and
changes nothing about how your Homey is set up. Meant for a
voice assistant you want on a short leash. Pick it per key, as
the access mode, or as the ceiling for remote connections.
v4.5.1 A refused action explains itself in a form your assistant can
read: a code, the tool, the permission that stopped it, and
whether retrying is pointless. And set_default false is honoured
instead of promoting the dashboard anyway.
v4.5.0 The permission model stopped guessing categories from tool
names, which refused a read-only key the trigger card list
because of the word "trigger" and treated tools that erase data
as harmless reads. Reading a HomeyScript now needs control
access, since script source can hold your API keys.
v4.4.1 Two remote-access fixes from a Cloudflare Tunnel report. The
consent page failed with "Origin not allowed", because the check
that protects against hostile web pages was also applied to the
OAuth pages, which are reached by redirect and can never match.
And a crash when a hostname resolved to IPv6 first.
v4.4.0 The Bridge device gets its own settings: refresh interval, and
an optional alarm for a burst of refused attempts that counts
the last 15 minutes so it clears by itself. Off by default.
v4.3.2 A new image for the Bridge device after App Store review
feedback, so it fits the store page it appears on.
v4.3.1 On a Homey this app cannot run on, the settings page kept
showing "server active" and 154 tools, left behind by an older
version. Refusing to start now clears them.
v4.3.0 Flows the AI builds run their actions at the same time instead
of one after another, since a chained action never runs at all
when the one before it fails. Deliberate sequences are left
alone and the reason is shown. The Bridge device gained four
values, and the daily counters are real: they used to be
estimated from recent log entries and flattened out around 200.
v4.2.1 A blocked tool is no longer advertised to your assistant and
then refused when called. Plus eight missing field labels in the
flow editor.
v4.2.0 Confirmation for irreversible actions is ON by default. It only
ever worked on clients that can show a prompt, and most cannot,
so a reboot or a delete simply went through while the app
presented confirmation as a headline feature. Access mode "off"
also really blocks everything now, where it used to keep handing
out device names and variable values. New: a Bridge device with
Insights graphs and flow triggers for the bridge itself.
v4.1.1 Fixes the version on the About tab, which read 3.1.3 whatever
you were running, and travelled into people's bug reports.
v4.1.0 A hardening pass, most of it found by attacking the app rather
than reading it. Confirmations could be skipped by wrapping a
call in a list or mixing protocol eras. A typo in the access
mode, or a key with an unrecognised permission, used to grant
FULL access. The browser-origin check compared two values the
attacker controls. And the settings page announced success
whether or not anything happened, including the button that
revokes an API key.
v4.0.2 Fixes a crash loop on older Homeys: the startup error escaped
initialisation, so Homey restarted the app over and over and
mailed a crash report each time. It now stops once and says
which Homey is needed.
v4.0.1 Dashboard widget URIs are checked before anything is written, so
a typo or an uninstalled app is refused with the reason instead
of showing up as a blank tile. Homey's own built-in widgets are
not exposed through any API, and the tools now say so and
describe the workaround.
v4.0.0 Rebuilt for the MCP 2026-07-28 spec while keeping every existing
connector working. The server speaks both eras side by side.
Confirmations now travel through the client, bound to the exact
tool, arguments and caller, so one can never be replayed against
another. Plus a long adversarial audit: a confirmation could be
skipped by wrapping the call in a batch, a client could opt out
by not declaring it could ask, browser pages elsewhere could
reach the server through DNS rebinding, and a corrupt guardrails
setting silently disabled every rule you had configured.
Earlier majors, in short
v3.x Native Homey Dashboards the AI can build, broken-flow detection
that resolves every card against the live registry instead of
trusting Homey's own flag, and the MCP 2025-11-25 spec with
server-initiated requests.
v2.x The release that turned a tool list into a bridge with a memory:
persistent memory across chats, scheduled actions, device events
with webhooks, the interactive dashboard, camera images, and the
whole security model the rest builds on.
v1.x The first release, 83 tools, then renamed to MCP AI Bridge. It
gained custom AI commands built from flow cards, optional API
key authentication, a REST shortcut with an OpenAPI spec, IP
whitelisting and rate limiting.
