> homey-developer-mcp

// 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.

  1. 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.

  2. Add the server to your client
    $ claude mcp add homey-developer --env HOMEY_PAT=pat-... -- npx -y homey-developer-mcp

    Add --scope user to use it in every project. Check the connection with /mcp.

  3. Test it

    Ask "List my Homey apps".

Environment variables

HOMEY_PATRequired. Your Personal Access Token.
HOMEY_MCP_ALLOW_WRITE1 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?
claude
> 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.

ToolReturns
list_appsYour 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, buildIdState 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, channelPuts 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, buildIdWithdraws 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.

More

Design decisions · Apps API notes