watchr-mcp 0.2.0

iOS Simulator QA agent — MCP server for Claude Code

Watchr — iOS QA Agent

AI-powered mobile app testing for iOS Simulator. Tell Claude Code what to test in plain English — it drives the simulator, finds bugs, checks accessibility, and catches crashes automatically.

Install (one time)

# 1. Install idb-companion (needed to control the iOS Simulator)
brew install idb-companion

# 2. Add watchr to Claude Code
claude mcp add --scope user watchr -- uvx --python 3.12 --upgrade watchr-mcp

That's it. Two commands. No repo to clone, no paths to manage. uvx downloads everything automatically. The --scope user flag makes watchr available in every project.

If you're missing anything, watchr will tell you exactly what to install when it starts.

Usage

Go to your app's project directory, open Claude Code, and type:

cd ~/Projects/my-ios-app
claude

Then tell it what to test:

Boot the simulator, launch com.yourapp.bundleid, and test the sign-up flow

Claude Code will:

• Boot the simulator
• Launch your app
• Navigate the flow you described
• Take screenshots at each step
• Report any bugs, crashes, or issues it finds

Note: Your simulator needs to be booted and your app installed on it. If not:

xcrun simctl boot "iPhone 16 Pro"
open -a Simulator
xcrun simctl install booted /path/to/YourApp.app

Example Prompts

"Test the sign-up flow end to end and report any bugs"

"Go to settings, verify all options are visible, check accessibility"

"Run monkey testing on the home screen for 30 seconds"

"Save a baseline screenshot of the landing page, then compare after my changes"

"Navigate to the payment screen and check if the app crashes"

What It Can Do

Capability	Description
Navigate any flow	Describe a user journey in English — it taps, swipes, types, and scrolls through it
Crash Detection	Checks if the app is still alive after every action, reads crash logs
Accessibility Audit	Finds missing labels, small touch targets, unlabeled buttons
Visual Regression	Saves golden screenshots, diffs against them to catch UI changes
Performance Timing	Measures screen load times, flags slow screens (>3s)
Monkey Testing	Random taps and swipes to find crashes scripted tests would miss
Text Verification	Asserts specific text is on screen, like Playwright's expect

Troubleshooting

Problem	Fix
idb commands fail	Run idb connect UDID with your simulator's UDID from xcrun simctl list
MCP server won't start	Run uvx watchr-mcp in terminal to see errors
Screenshots are blank	Make sure the Simulator app is open and visible
"No booted simulator found"	Boot one with xcrun simctl boot "iPhone 16 Pro"
App not launching	Verify the bundle ID with xcrun simctl listapps booted

Update

Watchr updates automatically — uvx fetches the latest version from PyPI each time Claude Code starts the server.

To force an update:

uvx --upgrade watchr-mcp