// MCP server for Homey app developers
Ask your AI assistant why your Homey app crashes.
Gives Claude, Cursor, VS Code and other MCP clients access to the crashes, diagnostic reports, builds and install stats of your Homey apps. It can also release builds and submit them for certification.
#Install
Requires Node.js 18 or newer. Your MCP client starts the server with npx, so there is nothing to clone or build.
-
Copy your Personal Access Token
It's on tools.developer.homey.app/me, under Personal Access Token, and starts with
pat-. The Homey CLI uses the same token, so keep it secret. -
Add the server to your client
$ claude mcp add homey-developer --env HOMEY_PAT=pat-... -- npx -y homey-developer-mcpAdd
--scope userto use it in every project. Check the connection with/mcp.Open Settings → Developer → Edit Config, add this to
claude_desktop_config.jsonand restart Claude Desktop.{ "mcpServers": { "homey-developer": { "command": "npx", "args": ["-y", "homey-developer-mcp"], "env": { "HOMEY_PAT": "pat-..." } } } }Add this to
~/.cursor/mcp.jsonfor all projects, or.cursor/mcp.jsonfor one.{ "mcpServers": { "homey-developer": { "command": "npx", "args": ["-y", "homey-developer-mcp"], "env": { "HOMEY_PAT": "pat-..." } } } }Add this to
.vscode/mcp.json. VS Code asks for the token once and stores it, so it isn't in the file.{ "inputs": [ { "type": "promptString", "id": "homey-pat", "description": "Athom Personal Access Token", "password": true } ], "servers": { "homey-developer": { "type": "stdio", "command": "npx", "args": ["-y", "homey-developer-mcp"], "env": { "HOMEY_PAT": "${input:homey-pat}" } } } }Run this as a stdio MCP server:
$ HOMEY_PAT=pat-... npx -y homey-developer-mcp -
Test it
Ask "List my Homey apps".
Environment variables
HOMEY_PAT | Required. Your Personal Access Token. |
HOMEY_MCP_ALLOW_WRITE | 1 enables the write tools. |
#Things to ask
- Which crashes happen most, and where in my code?
- What do this week's diagnostic reports say? Do any share a cause?
- Did crashes go down after build 41?
- Is my latest build through processing? What did the reviewer say?
- Release build 42 to test and submit it for certification.
- How did my installs change over the last 30 days?
> What do the new diagnostic reports for my thermostat app say? ● list_diagnostic_reports(appId: "com.example.thermostat") └ 2 reports in the last 5 builds ● get_diagnostic_report(logId: "a1b2c3d4-…") └ user message, 18 lines of stdout, stderr: ETIMEDOUT The device goes unavailable every evening. The log shows polling failing with ETIMEDOUT after the hub's nightly firmware check, and the app doesn't retry. Add a retry with backoff in drivers/thermostat/device.js. …
#Tools
Read tools are always available. They cover your own apps and those of your Developer Organizations.
| Tool | Returns |
|---|---|
list_apps | Your apps: live and test version, installs, rating, crashes. |
list_buildsappId, limit? | Builds of an app, newest first: state, installs, crashes. |
get_crashesappId, builds?, buildId?, kind?, limit? | Crashes and unhandled rejections, grouped by error and the line in your code that caused them. |
list_diagnostic_reportsappId, builds?, buildId? | Reports users sent from your app's settings: Log ID, their message, start of stderr. |
get_diagnostic_reportappId, logId, builds? | One report: user message, stdout and stderr. |
get_build_statusappId, buildId | State of a build, why processing failed, reviewer comments, Athom's AI review. |
get_install_statsappId, days?, perDriver? | Installs per day, optionally per driver. |
Write tools
Only available with HOMEY_MCP_ALLOW_WRITE=1. Clients that support it ask for confirmation before each call.
release_buildappId, buildId, channel | Puts a build on test or live. Athom only accepts live after the build passed review. |
submit_for_certificationappId, buildId, autoRelease? | Sends a build to Athom for review. With autoRelease (default false) it goes live once approved. |
retract_submissionappId, buildId | Withdraws a build from review. |
#How it works
The server exchanges your token for an apps API token, like the Homey CLI does, and reads from apps-api.athom.com.
Athom returns crashes, unhandled rejections and diagnostic reports from the same endpoint. The server tells them apart by their first line, and splits diagnostic reports into Log ID, message, stdout and stderr.
Homey counts an error that contains a device id separately for every device. get_crashes merges those by error message and the first line of your own code in the stack.
Crashes and reports belong to the build the user ran. The tools search your 5 newest builds; pass builds or buildId to go further back.
Waiting for a build
The server can't send notifications. In Claude Code, use /loop to call get_build_status periodically. For notifications on your phone, use the build triggers of App Insights for Developers on your Homey.
Privacy
Diagnostic reports contain your users' messages and logs, including device names. The tools pass them to the AI assistant you connect.