Skip to main content
Glama
per-simmons

monocle

by per-simmons
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Monocle

Playwright for Mobile — Give AI agents the ability to test any iOS mobile app.

Monocle is an open-source MCP server + visual dashboard that lets AI agents (Claude Code, Cursor, etc.) interact with iOS simulators through 21+ tools: tap, swipe, type, screenshot, inspect elements, wait for conditions, record sessions, and more.

Architecture

┌─────────────────────────────────────────────────────┐
│            Monocle Dashboard (Next.js)               │
│  Live Simulator View + Agent Chat + Action Timeline  │
└───────────────────────┬─────────────────────────────┘
                        │ HTTP + WebSocket (:7200)
┌───────────────────────▼─────────────────────────────┐
│            Monocle Server (Node.js)                  │
│  MCP Server (stdio+HTTP) + REST API + WS Streaming   │
│  21+ tools • Element refs (@e1) • Session recording  │
└───────────┬────────────────────────┬────────────────┘
            │                        │
     idb_companion              xcrun simctl
     (accessibility,            (screenshots,
      tap, swipe, type)          recording, lifecycle)

Related MCP server: iOS Device Control MCP Server

Quick Start

# Prerequisites: Xcode 15+, Node.js 20+, idb_companion
npm install
npm run dev

# Or use via MCP (stdio mode for Claude Code):
npx tsx packages/server/src/index.ts --stdio

MCP Configuration

{
  "mcpServers": {
    "monocle": {
      "command": "npx",
      "args": ["tsx", "/path/to/monocle/packages/server/src/index.ts", "--stdio"]
    }
  }
}

Tools (21+)

Category

Tools

Screen

screenshot, getScreenText

Interact

tap, tapByText, tapById, doubleTap, longPress, swipe, type, typeInto, pressKey

Inspect

listElements, findElement, getElementInfo

Wait

waitForElement, waitForText, assertVisible

Device

listDevices, launchApp, terminateApp, getDeviceInfo, openUrl

Record

startRecording, stopRecording

Element Refs

Monocle assigns short refs (@e1, @e2, ...) to every UI element. Use them anywhere:

Agent: "tap @e3"  → taps the Login button
Agent: "type into @e5 'hello@example.com'"  → types into email field

Refs are stable within a session — same element keeps the same ref across calls.

Packages

  • packages/server — MCP server, iOS bridges, streaming, sessions

  • packages/dashboard — Next.js visual dashboard

  • packages/cli — CLI (monocle start, monocle devices, monocle screenshot)

Prerequisites

  • macOS with Xcode 15+

  • At least one iOS Simulator booted

  • idb_companion installed (brew install idb-companion)

  • Python 3.11 venv with fb-idb (for accessibility tree)

License

MIT — Pivot Studio AI

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers