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. 170 actions, your own custom AI commands in the flow editor, a flow card that asks a model a question, and dashboards for your wall and for Homey’s own app. 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. 170 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.
See it before it happens, and take it back. Ask for a preview and you get what would change instead of the change. A set of twelve renames is shown in full and applied as one thing, with the ones that went through put back if a later one fails. The last change an assistant made can be undone.
Pick which tools each assistant sees. Per key, tick exactly what that connection is shown, with a running count that warns you when you pass the 100 several clients refuse to go past.
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.”
- “Tell me when the basement sensor goes offline.”
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
170 actions in total, so the assistant can both understand the state of your home and act on it. There is also one call that answers the shape of the whole house at once, so a fresh conversation starts oriented instead of reading four full listings first.
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. The tab opens on mcp-remote, which needs Node.js on your computer, because older builds answer a native HTTP entry with “not valid MCP server configurations”, which reads as a broken app rather than a config the client does not know.
{
"mcpServers": {
"homey": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://<homey-ip>:52199/mcp", "--allow-http"]
}
}
}
Newer builds do take the native form, on the second button of that tab:
{
"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. The Claude Desktop, Claude Code and Cursor tabs each have an mcp-remote button that writes the same npx form as the Claude Desktop block above. Gemini and Copilot take the native entry only.
With an API key set, the key travels as a header, but every form writes it down differently. The wizard fills it in for you; these are the shapes it produces:
native HTTP entry "headers": { "Authorization": "Bearer YOUR_API_KEY" }
mcp-remote (npx) two more args: "--header", "Authorization: Bearer YOUR_API_KEY"
claude mcp add --header "Authorization: Bearer YOUR_API_KEY"
vibe mcp add --header "Authorization=Bearer YOUR_API_KEY"
Vibe config.toml headers = { "Authorization" = "Bearer YOUR_API_KEY" }
Note the Vibe command: an equals sign where the others take a colon.
On a fresh install the wizard pastes the real key straight in, because the app made it and you have not seen it yet. Once it has been shown it is write-once again and you get the placeholder to replace.
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.
Ask a model a question, from a flow
- Action: “Ask a model a question.” Your flow asks, the answer comes back as a tag called Answer, and you use it in whatever comes next: a notification, spoken out loud, into a variable, into a condition. It uses your own API key with Anthropic, OpenAI or Mistral, so it is off until you set it up, and there is a daily limit so a flow that fires more often than you expected cannot run up a bill. You choose what goes with the question: nothing, one room, one device, what happened recently, or the whole home. Text in, text out: the model cannot call tools, cannot see your home beyond what you chose to send, and cannot change anything.
Let a flow branch on what a model says
- Condition: “A model answers yes.” The flow asks a yes or no question and takes a different path. The model is told to answer with one word, and if it says something that is neither, the flow stops and quotes what it said rather than guessing a branch for you.
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. Works in a basic flow and in an Advanced Flow: a basic flow becomes a tool within seconds, an Advanced Flow within five minutes, because Homey sends no live signal when one of those changes.
- Ask your assistant for
flow_tools_describeto give such a tool a description, up to five typed arguments (they arrive in the flow as Argument 1 to 5) and a longer wait for its answer. Without that it waits ten seconds and takes whatever text the assistant sent as one input.
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.
- Trigger: “A scheduled bridge job fails.” Nobody watches a schedule, which is exactly why it needs a card.
- Trigger: “An AI agent disconnects.” And the condition “An AI agent is connected”, for a flow that should only run while one is.
- Condition: “The security event is.” Alarm on one kind of refusal and ignore the others.
- Condition: “Model spend today is below.” Uses the prices you filled in, and stops with a reason when there are none.
Limit the bridge from a flow
- Action: “Limit the bridge to a mode.” Everyone asleep, bridge to read only. Never above the mode you chose on the settings page, because an assistant can start a flow, and a card that could raise access would let it lift its own limit.
- Action: “Return the bridge to its normal access mode.” Puts your chosen mode back, and nothing higher.
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, in whichever kind of flow you already build in.
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.
A morning summary in your own words
- Trigger: every day at seven.
- Action: Ask a model a question, with the summary of the home included: “what stands out about the house this morning, in two sentences”.
- Action: send the Answer tag to yourself as a notification.
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 which tools, per key. Press Tools on a key and tick exactly what that connection is shown, grouped by what each tool does, with a search box and a running count. There are quick choices too, including “only what has been used” and “under 100”, which is the limit several clients refuse to go past. Each tool shows how often it has actually been used, so the list is not a quiz. A selection only ever narrows: you are offered only the tools that key’s permission already allows, so trimming a list to fit a client can never hand out access by accident.
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.
A new install makes itself an API key, so the bridge is never open to everything that can reach your Homey. It is shown once on the Status tab, and while it is there the connect wizard fills it into the config for you. An install that was already running keeps working exactly as it is: you get one notification and a button that makes a key when you want one.
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
Thirteen 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.
Ask a model is the other direction: which provider, your own API key, the daily limit, a second provider to fall back on, what your provider charges per million tokens, and a test question you can ask straight from the page. Underneath it, the last twenty questions this home asked with what they cost, so a flow that ran overnight is not a mystery in the morning.
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, Schedules 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. Schedules also holds the optional daily summary: one notification saying how many calls there were, how many failed, what was refused and whether any flows are broken.
Diagnostics is every action with its result, how long it took and which key it came from, 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.
It runs on the Homey Pro models from 2023 on, with firmware 12.1.0 or newer. A Homey Pro (Early 2019) or older cannot run it.
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.18.1 Custom tools can be built in an Advanced Flow too; only basic
flows were read. Such a tool shows up within five minutes,
since Homey gives no live signal for Advanced Flows. The
broken-flow check no longer calls a flow broken for a card that
points at its own app's script or dashboard, and a refused
install, backup, rename or restart names the scope it needs.
v4.18.0 The whole app read through, and everything it turned up, built.
It now needs Homey firmware 12.1.0, for a widget on Homey's own
dashboards. A room inside a floor counts, so "everything off
downstairs" works, and schedules take a clock time and weekdays
that hold through daylight saving. Energy reports per period,
prices, Matter and Thread state, app usage and a backup on
request. Diagnostics you can search per key, and a change
history that stays off until you switch it on. New flow cards
for a failed schedule, a disconnect and spend below an amount,
and a card that limits the bridge, never above what you chose.
Every dashboard page got its own token, so one page cannot
drive what only another shows, plus live statuses on the
security tab, dimmed values when a sensor goes quiet, logic
variables, live charts, cover sliders, the weather and flow
tiles. Assistants get progress, cancelling, one item by id,
watches on a device going offline, on presence and on a
variable, and a way to look up the valid values of a card field
instead of guessing.
v4.17.0 Ask a model grew the halves it was missing: every question is
recorded with the provider, the model and the tokens, a
condition card lets a flow branch on a yes or no answer,
context can be aimed at one room or one device, the prices you
fill in turn tokens into real money per question and per day,
and a second provider is tried once when the first cannot be
reached. It reaches the Bridge device and both dashboards.
Earlier 4.x, in short
v4.15.1 The test question on the Ask a model tab answered "Missing
implementation for api endpoint" instead of asking anything.
Reported by Mark1541; one routing file never got the endpoint.
v4.15.0 A flow can ask a model a question with your own key and use
the answer. Off until you switch it on, with a daily limit.
Text in, text out: the model gets no tools and changes nothing.
v4.14.0 A set of changes is shown before it happens and applied as one
thing, with what went through put back if one fails. The log
says which key did it, and home_briefing orients an assistant
in 3 KB instead of the 31 KB four listings used to cost.
v4.13.0 How often each tool is really used when you pick tools for a
key, dry_run for what a call would do, undo for the last
change, listings you can ask less of, and a daily summary.
v4.12.3 Fixes the handshake that locked out everyone on mcp-remote,
reported by Paul_Pandre. The protocol era is now read from the
message instead of from headers ordinary clients also send.
v4.12.1 The tool selection on a key now also reaches a connection from
outside, which used to be shown every tool anyway.
v4.12.0 Pick per API key exactly which tools an assistant is shown,
for clients that cap a connector at 100. It only ever narrows.
v4.11.0 A new install gives itself an API key, so the bridge is never
open to everything on your network. Running installs keep
working exactly as they did.
v4.10.1 Mistral Vibe in the connect wizard, the one client that wants
TOML where every other takes a JSON map.
v4.10.0 Camera tiles proxied by the app, cards and rows that appear
only when a condition holds, a dashboard list in the settings,
a button that creates three moods per room, and a switch to
stop serving the dashboard on your network.
v4.9.2 The settings page gone through tab by tab, because most of it
assumed you had built the thing. Example commands went from
seventeen to seventy-eight.
v4.9.1 One bug report instead of two, where the page and your
assistant each built a document missing what the other had.
v4.9.0 A full security audit: four ways to get more access than you
were given, closed. The dashboard is local-network-only again.
v4.8.0 The bridge can serve HTTPS itself, so the last hop from your
proxy stops being plain HTTP with your key in the clear. Plus a
list of the cloud assistants you approved, and a way to revoke.
v4.7.0 Your assistant is only shown the tools its key may use, and is
told which permission it is on.
v4.6.0 A fourth permission level, Control only: it operates the house
and changes nothing about how the house is set up.
v4.5.1 A refused action explains itself in a form your assistant can
read, instead of a bare failure.
v4.5.0 The permission model stopped guessing categories from tool
names, which had refused reads and waved through deletes.
v4.4.1 Two remote-access fixes from a Cloudflare Tunnel report.
v4.4.0 The Bridge device gets its own settings, including an optional
alarm for a burst of refused attempts.
v4.3.2 A new image for the Bridge device after App Store review.
v4.3.1 On a Homey this app cannot run on, the settings page no longer
shows a server that is not there.
v4.3.0 Flows the AI builds run their actions at the same time, since a
chained action never runs at all when the one before it fails.
v4.2.1 A blocked tool is no longer advertised and then refused.
v4.2.0 Confirmation for irreversible actions is ON by default, and
access mode "off" really blocks everything. New: a Bridge
device with Insights graphs and its own flow triggers.
v4.1.1 Fixes the version on the About tab, which read 3.1.3 whatever
you were running.
v4.1.0 A hardening pass, most of it found by attacking the app rather
than reading it, including a typo in the access mode that used
to grant full access.
v4.0.2 Fixes a crash loop on older Homeys.
v4.0.1 Dashboard widget URIs are checked before anything is written.
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, and a confirmation is bound to the exact tool, arguments
and caller so it can never be replayed against another.
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.
