Owl Watch Simulator MCP · help
Set up an AI agent to test a watch app in the simulator.
Owl Watch Simulator MCP is an MCP server that lets an AI coding agent such as Claude Code build a watch app, run it in Garmin’s Connect IQ simulator, see the screen and press the buttons. This page is how to set it up, what to ask for, and where it stops.
Setting it up
You need a Mac with macOS 14 or later. Then four steps, once.
- Install what it builds with. Garmin’s Connect IQ SDK with at least one device, a Java runtime, a Connect IQ developer key, Node.js 20 or later, and Xcode Command Line Tools, which compile the tool’s small native helper when it installs.
- Add it to Claude Code. In a terminal, run
claude mcp add owl-watch-simulator -- npx -y owl-watch-simulator-mcp. Another MCP client starts it withnpx -y owl-watch-simulator-mcp; the README on GitHub has the steps. - Grant Accessibility and Screen Recording, in System Settings › Privacy & Security, to the app you start it from: your terminal or your IDE, then restart it. macOS grants them to that app, not to the server itself.
- Check, then ask.
npx -y owl-watch-simulator-mcp --doctorchecks the SDK, Java, your developer key, the native helper and the permissions, and says what is missing. Then ask your agent to run the app: one call builds it, launches it in the simulator and returns the screen, with any compiler errors as file and line.
What to ask your agent
Ask in plain words; the agent chooses among the tool’s 25 tools. Three things it is for:
- Run the app and look. “Build the app and show me the main screen.” One call,
run_app, builds, launches and returns the screen, so the agent sees what its change did. - Walk a flow by name. Every action returns the picture and the text recognised on it, with tap-ready positions, so the agent can tap a button by its label with
tap_textand wait for the next screen withwait_for: “tap Trains, and check the routes appear”. - Check more than one case. Run the same steps on several devices in one call, set a GPS position, read the app’s log, or run its unit tests.
Where it stops
It runs on macOS only. It drives the simulator, not a real watch, so what the agent checks is what the simulator shows. It touches nothing but the simulator. A long press or held button moves your real pointer to the target for about a second, then puts it back, so someone at the Mac sees it jump; and soon after launch a hold can register as a short press, which is a known issue. Everything it returns — screenshots, the text on them, the app’s log — goes to your agent, and from there to the model your agent uses: for Claude Code, Anthropic’s API.
Questions
The things developers ask.
Does it work on Windows or Linux?
No. Owl Watch Simulator MCP runs on macOS 14 or later only: it reads the simulator’s text with Apple’s Vision framework and presses its buttons through macOS’s Accessibility permission. It was developed and tested on macOS 27, on Apple silicon; earlier macOS releases have not been run.
Which AI agents and MCP clients does it work with?
It is an MCP server, so it is for MCP clients. Claude Code is the client it was built and tested with: add it with claude mcp add owl-watch-simulator -- npx -y owl-watch-simulator-mcp. Another MCP client starts it with npx -y owl-watch-simulator-mcp, but has not been tested by us.
Is Owl Watch Simulator MCP free, and what is the licence?
It is free, and open source under the MIT licence; the code is on GitHub and the package on npm, as owl-watch-simulator-mcp. It is provided as is, with no warranty: you use it at your own risk, and The Owlery Works accepts no responsibility for what it, or your agent, does.
What does it send, and to whom?
Nothing to us: its only network connection is to the simulator on your own Mac, and there is no telemetry, analytics or account. What it returns — pictures of the simulator’s screen, the text read from them, your app’s log and the build’s output — goes to your AI agent, which sends it to the model it uses, under that company’s terms; for Claude Code, that is Anthropic’s API.
Why can’t the agent see or press anything?
Usually because Accessibility and Screen Recording were granted to the wrong app. macOS grants them to the app that launches the server — the terminal or IDE you run your agent from — not to the server itself. Grant both to that app in System Settings › Privacy & Security. A dialog open in the simulator can also block input.
Does it run my app on a real watch?
No. Owl Watch Simulator MCP drives Garmin’s Connect IQ simulator on your Mac and does not run the app on a real watch. What your agent checks is what the simulator shows, so try the app on a watch before you publish it.
Still stuck?
Open an issue on GitHub, or raise a case here, with or without an email address. Say which macOS, which device in the simulator, and the version simulator_status reports.