Garmin Simulator MCP
Provides tools for building Garmin Monkey C projects with the Connect IQ SDK, loading apps into the Garmin simulator, driving watch buttons/touch gestures, capturing screenshots, and reading app logs and crash output.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Garmin Simulator MCP build and run my watch app, then take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Garmin Emulator MCP
█████████
████████·······████████
█████·····················█████
LIGHT ▐ ████··┌─────────────────────┐··████ ▌ START
████····│ M C P │····████
████·····│ │·····████
███······│ > ready_ │······███
UP ▐ ████······│ │······████
███······│ │······███ ▌ BACK
████·····│ build run │·····████
████····│ │····████
DOWN ▐ ████··└─────────────────────┘··████
█████·····················█████
████████·······████████
█████████Watch apps are awkward to test. The screen is tiny, there is no keyboard, and the simulator expects a human with a mouse. This puts the simulator behind an MCP server so an AI coding agent can run the same loop you would: build, look, press, look again, read the log.
What it does
Capability | What you get |
Build | Compiles a Monkey C project with the Garmin SDK and loads it into the simulator. |
Drive | Presses the physical buttons, taps, swipes and long-presses the watch screen. |
Isolate | Runs the simulator on a hidden desktop, so it never takes over your screen. |
Inspect | Screenshots of the watch display, the bezel, or an annotated debug view. |
Read | App logs and crash output streamed back to the agent. |
Check | SDK, device profiles, signing key and simulator state before every run. |
State | Reads and seeds app storage and debug property overrides, resets data and moves the app clock. |
Message | Sends a phone-app message into the app and reads the stored payload back. |
Coverage | Builds and captures the same screen, and optional button or touch steps, across several devices. |
Loop | Builds, runs and returns the first frame and log tail in one call. |
Related MCP server: iOS Simulator MCP Server
The loop
Step | What happens |
1 | The agent checks the setup and launches the simulator. |
2 | It builds your project and runs it on the selected device. |
3 | It presses through the screens you describe. |
4 | It looks at the result and reads the logs. |
5 | It repeats until the screen matches what you wanted. |
Requirements
Need | Why |
Node.js 18 or later | Runs the server. |
Java | Runs the Garmin compiler. |
Connect IQ SDK Manager | Provides the SDK, simulator and device profiles. |
A developer signing key | Signs your app for the simulator. |
macOS 13 or Windows with PowerShell 5.1 | Supported hosts. Windows uses a hidden desktop by default; an unlocked desktop is only needed for the visible fallback. |
Quick start
Step | Command |
Install |
|
Build |
|
Connect | Point your MCP client at |
Ask the agent to check the setup, launch the simulator, build your project and take a screenshot. Setup examples for common clients are in AGENT-README.md.
npm install can print install-script warnings from sharp, esbuild or fsevents. They are dependency build messages, not server errors; npm run build is the check that matters.
Good to know
Topic | Detail |
One at a time | One simulator, one server. A second instance refuses to start so two agents cannot fight over the same device. |
Focus | Button presses need an unlocked, interactive desktop. Screenshots, logs and menu actions keep working in the background. |
Best effort | The watch screen is not exposed as native controls, so the server verifies each press by comparing screenshots. |
Local state | Session logs and captures are written under your app data folder, not into the project. |
Agent reference
AGENT-README.md lists every MCP tool and its parameters.
License
Apache-2.0.
Available Tools
46 toolsact_on_uiB
Act on a freshly inspected native simulator element. set writes AXValue; AXPress activates controls. Pass hwnd for dialogs.
Inputs: path (required), action (required), hwnd, value.
build_appC
Build a Monkey C project for a specified device using the SDK monkeyc compiler.
Inputs: project_dir (required), device_id, extra_args, timeout_ms, +4 more.
calibrateB
Report window, bezel and display geometry plus every button centre mapped to screen coordinates, and check each point is inside the window. Optionally save a raw screenshot.
Inputs: grid, verify, device_id, save_path.
capture_windowA
Capture a simulator-owned dialog or window by hwnd. Returns the PNG image and optional saved path.
Inputs: hwnd (required), save_path.
close_storage_editorA
Close the simulator's persistent-storage editor and verify the window is gone. Safe when already closed.
Inputs: no named parameters.
close_windowA
Close a simulator-owned dialog by hwnd. Refuses to close the main simulator window.
Inputs: hwnd (required).
debug_commandB
Send a raw command to the in-app debug channel. Verbs: ping, state, seed, premium, deck_list, list, map, time, phone, reset; arguments are semicolon-free strings.
Inputs: verb (required), args, timeout_ms.
debug_pingA
Round-trip a ping through the in-app debug channel. Proves the app is running and polling without touching focus.
Inputs: timeout_ms.
debug_statusA
Report the local debug channel endpoint, whether the app has polled it, and the last command result.
Inputs: no named parameters.
dev_loopA
Build the project, run it, capture the first stable frame and return the latest log lines in one call.
Inputs: project_dir (required), wait_ms, device_id, log_lines, +4 more.
diff_screenshotA
Compare a baseline PNG with another PNG or with the current simulator screen. Returns the changed percentage and the bounding box of change.
Inputs: before_path (required), threshold, after_path.
doctorB
Check the SDK, toolchain, device profiles, developer key, simulator window, occlusion and session log before blaming an app failure on the app.
Inputs: project_dir.
get_app_logsA
Retrieve console output, System.println logs, and crash traces from the running Monkey C application and simulator. Logs are also appended to a session file, so a reconnect does not lose history.
Inputs: clear, lines, since_seq.
get_screenshotB
Capture a screenshot of the Connect IQ simulator. Supports watch display crop ('screen', 1:1 pixel mapping), full window with bezel ('bezel'), or annotated debug view with button hitboxes and coordinate grid ('annotated').
Inputs: mask, view, format, region, +5 more.
hold_screenB
Long-press at specific coordinates on the watch touchscreen (e.g. to open a watchface complication or menu).
Inputs: x (required), y (required), expect, wait_ms, +5 more.
inspect_uiA
Read simulator Accessibility hierarchy, including menus and native dialogs. Pass hwnd to inspect a dialog from list_windows. Paths are ephemeral: inspect before acting.
Inputs: hwnd, depth.
launch_simulatorA
Launch the Garmin Connect IQ simulator, by default on a hidden Windows desktop where button input does not change your foreground window.
Inputs: wait_ms, isolated.
list_devicesA
List all installed Garmin device profiles in Connect IQ SDK Devices directory with display resolutions, touch support, screen shape, and available buttons.
Inputs: query, touch_only.
list_windowsA
List top-level simulator windows, including storage, login, time and phone-message dialogs. IME and hidden wx windows are filtered unless include_hidden is true.
Inputs: include_hidden.
matrix_diffC
Compare every baseline PNG in a directory with the matching current PNG and report changed percentage and bounds.
Inputs: baseline_dir (required), threshold, output_dir.
matrix_runB
Build, run and capture one screen per device, optionally run a button/touch scenario, and compare each step against .ciq/baselines. Creates baselines when missing or when update_baselines is true.
Inputs: devices (required), project_dir (required), steps, wait_ms, +10 more.
phone_messageA
Deliver a phone-app message to the running app through the debug channel and let the app handler store it. Use state_read to verify last_phone_message.
Inputs: body, title, timeout_ms.
place_windowB
Move or clamp the simulator window inside the nearest monitor work area. With no coordinates it only rescues a window that is mostly off-screen.
Inputs: x, y, width, height.
press_buttonB
Press a physical bezel button on the active Garmin device (e.g. 'select', 'back', 'up', 'down', 'menu'). Supports short clicks or long-press holds, and returns the updated watch screen.
Inputs: button (required), hold, expect, method, +5 more.
press_button_sequenceA
Execute a sequence of button presses in order with configurable delays, capturing the final watch screen.
Inputs: steps (required), expect, isolated, device_id, +2 more.
recognize_image_textA
Recognize text in a saved simulator PNG using on-device OCR. Returns text and normalized bounds; confidence is available on macOS. OCR is evidence, not a replacement for storage assertions.
Inputs: image_path (required).
reset_stateA
Reset persisted app data through the simulator menu, with a screenshot and optional APPS snapshot first. Requires confirm: true. Restart the app afterwards to observe a clean launch.
Inputs: confirm (required), scope, verify, wait_ms, +4 more.
restore_app_filesA
Restore a verified app-scoped snapshot. Requires explicit confirmation and a stopped app; never use while app/background writes are active.
Inputs: app_names (required), directory (required), confirm_stopped (required).
run_appB
Push and run a compiled Monkey C executable (.prg) on the active device in the simulator using monkeydo, and stream logs.
Inputs: prg_path (required), wait_ms, device_id, timeout_ms, +2 more.
run_unit_testsA
Run Monkey C unit tests for a compiled .prg test binary in the simulator using monkeydo -t.
Inputs: prg_path (required), device_id, test_name, timeout_ms.
send_keyC
Send a platform virtual key code or named key ('enter', 'esc', 'up', 'down', 'menu', 'space') to the Connect IQ simulator window.
Inputs: key, expect, hold_ms, wait_ms, +4 more.
session_startA
Report whether this server adopted a simulator left by an earlier session or started clean. Use reset: true to terminate the adopted simulator and clear the stored session.
Inputs: reset.
set_active_deviceA
Set the active Garmin device ID for subsequent simulator commands, button presses, touch gestures, and screenshot cropping.
Inputs: device_id (required).
set_glance_modeB
Toggle or set the simulator Glance View mode (Settings > Glance View) for testing widget glance summaries.
Inputs: enabled, wait_ms, capture_after.
set_timeB
Shift the app's clock through the debug channel. Use an ISO timestamp or an offset in seconds. Only code paths using DebugClock follow the offset.
Inputs: iso, clear, timeout_ms, offset_seconds.
simulator_statusA
Inspect Connect IQ simulator process status, window ID, bounds, macOS Screen Recording and Accessibility permissions, TCP port 1234 status, and active device profile metadata.
Inputs: no named parameters.
snapshot_app_filesB
Back up only files matching explicit PRG basenames from simulator APPS. Does not stop the app; use an idle/stopped session.
Inputs: app_names (required), directory (required).
state_readA
Read the app's storage and property state through the in-app debug channel. Values are scalar summaries; arrays report size.
Inputs: keys, timeout_ms.
state_resetB
Clear every app storage key through the in-app debug channel and optionally report the resulting state.
Inputs: verify, timeout_ms.
state_seedB
Write storage keys through the in-app debug channel, then optionally read them back to verify. Use null to delete a key.
Inputs: values, verify, prg_path, snapshot, +5 more.
stop_appB
Stop the currently running Garmin Monkey C app process in the simulator.
Inputs: no named parameters.
swipe_screenB
Synthesize a touch drag gesture on the watch display in a cardinal direction ('up', 'down', 'left', 'right'), adhering to device gesture thresholds.
Inputs: direction (required), expect, wait_ms, device_id, +2 more.
tap_screenB
Tap the watch touchscreen at specific display coordinates (X, Y) or normalized coordinates (0.0..1.0).
Inputs: x (required), y (required), expect, wait_ms, +4 more.
terminate_simulatorB
Terminate only ConnectIQ.app and destroy its isolated desktop if one was used. Force is for an unresponsive simulator. Does not delete stored data.
Inputs: force.
wait_for_stableA
Wait until two consecutive simulator captures are identical, so screenshots and assertions are not taken mid-animation.
Inputs: settle_ms, timeout_ms, interval_ms.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 46 tools
The broad domains are distinct (lifecycle, input, capture, debug, files), but several boundaries blur: debug_command overlaps state_read/state_seed/state_reset/set_time/phone_message, and reset_state/state_reset/debug_command reset all touch reset behavior. matrix_run vs. build+run vs. dev_loop, and capture_window/get_screenshot/diff_screenshot also require careful reading to choose correctly.
Names are consistently snake_case and mostly action-oriented, which makes the set readable. The pattern varies between verb_noun (get_screenshot, list_devices), noun_verb (session_start, state_read, simulator_status), and bare utility names (doctor, calibrate), but this is a minor deviation rather than a different convention.
At 46 tools, the surface is heavy for a simulator-control server, with many one-off diagnostic, matrix, window, and debug helpers. While the domain is genuinely broad, the count exceeds a well-scoped set and invites tool-selection overhead.
Coverage is strong across lifecycle, build/run, input simulation, screenshots/diffs, debug-channel state, file snapshots, windows, and diagnostics. Minor gaps remain around explicit baseline management (listing/deleting baselines) and app install/uninstall-style operations, but core workflows are well supported.
Maintenance
Related MCP Connectors
Launch and verify high-fidelity mobile simulations from an AI agent.
Cloud iPhone Simulators for AI agents: build the Xcode project, read the screen, tap by label, test.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to automate iOS Simulator interactions including device management, UI element interaction (tap, swipe, type), screenshot capture, and execution of YAML-defined navigation workflows.15 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to control iOS Simulators for UI/UX debugging, app management, and accessibility auditing via simctl, IDB, and ClaudeDebugKit.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to build, launch, inspect and drive Garmin Connect IQ apps in the macOS Connect IQ simulator, returning screenshots paired with recognised on-screen text and tap-ready coordinates. It runs whole interaction flows—including the same steps across several watch devices—in a single call, without needing the simulator to be frontmost or the screen unlocked.16 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to check setup, manage iOS Simulator devices, build/install/launch iOS apps, capture screenshots, send input, and open a live browser preview. It connects local agent workflows to Apple's simulator without requiring a custom emulator or native pane.MIT