Skip to main content
Glama
Garmin Simulator MCP
by dqclqn

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

npm install

Build

npm run build

Connect

Point your MCP client at dist/index.js.

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 tools
act_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.

trigger_menu_actionC

Trigger a macOS menu item in ConnectIQ.app via Accessibility (AXUIElement), such as simulation data or activity settings.

Inputs: menu_path (required), wait_ms, capture_after.

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

    B3.2/5.0

    Scored across 46 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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