{"id":"365c18ee-ef4e-4130-8f27-fc7bfb992e0b","slug":"touchbridge-mcp","kind":"mcp","name":"touchbridge-mcp","summary":"Local-first MCP control, testing, and design capture for iOS","owner":"MarshallBear1","repoUrl":"https://github.com/MarshallBear1/touchbridge-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-07-30T18:44:51.000Z","addedAt":"2026-10-21T09:22:07.194Z","logoUrl":"https://avatars.githubusercontent.com/u/126336809?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","design-media"],"tags":["ai-agents","automation","figma","ios","iphone","testing","ios-automation","physical-device"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T09:22:28.150Z","sample":false,"url":"https://conduits.dev/tools/touchbridge-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"touchbridge-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n  <img src=\"./assets/touchbridge-mark.svg\" width=\"108\" alt=\"TouchBridge logo\" />\n  <h1>TouchBridge</h1>\n  <p><strong>Local MCP control, inspection, and design capture for iOS.</strong></p>\n\n  [![CI](https://github.com/MarshallBear1/touchbridge-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MarshallBear1/touchbridge-mcp/actions/workflows/ci.yml)\n  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n  [![Node.js 20.17+](https://img.shields.io/badge/node-%3E%3D20.17-339933.svg)](package.json)\n</div>\n\nTouchBridge lets an MCP-compatible AI host inspect and operate iOS simulators and physical iPhones. It also creates structured design snapshots: a full-resolution screen image, redacted accessibility metadata, normalized editor layers, and a versioned handoff manifest.\n\nThe server runs locally over stdio. Normal device control does not require a TouchBridge cloud service.\n\n> [!IMPORTANT]\n> TouchBridge is pre-1.0 software. Test destructive or account-changing flows on non-production data, keep physical devices unlocked during automation, and review the [security and privacy boundaries](#security-and-privacy) before capturing sensitive screens.\n\n## What works\n\n| Capability | Simulator | Physical iPhone/iPad |\n|---|:---:|:---:|\n| Discover active targets | Yes | Yes |\n| Tap, swipe, and enter text | Yes | Yes, through WebDriverAgent |\n| Scan visible interactive elements | Yes | Yes |\n| Read the accessibility hierarchy | Yes | Yes |\n| Capture temporary screenshots | Yes | Yes |\n| Capture durable design snapshots | Yes | Yes |\n| Launch an app by known bundle ID | Yes | Yes |\n| List installed apps | Yes | Not yet |\n| Loopback live viewer | — | Yes |\n| Structured environment diagnostics | Yes | Yes |\n\nPhysical-device automation does not support numeric HID keycodes. Use text keys, touch actions, or supported hardware-button actions instead.\n\n## Requirements\n\n- macOS\n- Xcode and its command-line tools\n- Node.js 20.17 or newer\n- Homebrew\n- Internet access during first-time installation\n\nPhysical devices additionally require:\n\n- a data-capable USB cable or a working CoreDevice network tunnel;\n- an unlocked, trusted iPhone or iPad;\n- Developer Mode enabled;\n- an Apple ID signed into Xcode for WebDriverAgent code signing.\n\n## Quick start\n\nCheck the environment before changing any MCP configuration:\n\n```bash\nnpx -y github:MarshallBear1/touchbridge-mcp --doctor\n```\n\nInstall the local dependencies and configure supported MCP hosts:\n\n```bash\nnpx -y github:MarshallBear1/touchbridge-mcp --setup-all\n```\n\n`--setup-all` configures detected Claude Code, Cursor, Codex, and OpenCode installations. Use `--setup-here` for project-scoped configuration or `--setup` for an interactive choice.\n\nRestart the MCP host, boot one simulator or connect one unlocked physical device, then ask:\n\n```text\nRun TouchBridge doctor, get the execution context, and describe the current screen.\n```\n\nTouchBridge exposes the MCP server with this command:\n\n```bash\nnpx -y github:MarshallBear1/touchbridge-mcp\n```\n\n## Physical-device setup\n\n1. Connect the device with a data-capable cable.\n2. Unlock it and accept **Trust This Computer** if prompted.\n3. Enable **Settings → Privacy & Security → Developer Mode**.\n4. Sign into **Xcode → Settings → Accounts**.\n5. Run `--setup-all`; TouchBridge clones the pinned WebDriverAgent release listed in `src/brand.ts`.\n6. Call the MCP `setup_device` tool with the physical UDID. If WebDriverAgent is not running, the tool returns exact build and launch commands.\n7. Keep the returned `xcodebuild test-without-building` process running while using the device.\n\nIf the Mac has certificates for multiple Apple teams, set the team shown in Xcode before starting the MCP host:\n\n```bash\nexport TOUCHBRIDGE_DEVELOPMENT_TEAM=ABCDE12345\n```\n\nUseful connection checks:\n\n```bash\nxcrun xcdevice list\nxcrun devicectl list devices\nnpx -y github:MarshallBear1/touchbridge-mcp --doctor\n```\n\nA device that is merely paired or remembered is not necessarily connected. If TouchBridge reports zero physical devices, unlock the phone, reconnect the cable, accept any trust/developer-image prompt, and retry.\n\n### Reproducible physical smoke test\n\nFrom a source checkout, this command exercises the real MCP transport without tapping, typing, or launching an app:\n\n```bash\nnpm ci\nnpm run smoke:physical -- --udid 00008150-EXAMPLE\n```\n\nThe smoke test performs:\n\n```text\ndoctor → list_devices → setup_device → get_screenshot → scan_ui\n```\n\nIt verifies and then deletes its temporary screenshot. It fails with the required WebDriverAgent setup instructions when WDA is not ready. Physical smoke tests are intentionally opt-in and do not run in GitHub Actions.\n\n### Verified physical-device matrix\n\n| Date | Device | iOS | Xcode | WDA | Result |\n|---|---|---:|---:|---:|---|\n| 2026-08-24 | iPhone Air | 26.5 | 26.6 | 16.8.0 | PASS: doctor, MCP setup, screenshot verification, and 24-element UI scan |\n\nThe verified run performed no taps, typing, button presses, or app launches.\n\n## MCP tools\n\n| Tool | Purpose |\n|---|---|\n| `doctor` | Diagnose Node, Xcode, Simulator, idb, image tooling, and connected targets |\n| `get_execution_context` | Resolve the active simulator/device and viewer state |\n| `list_devices` | List booted simulators and connected physical devices |\n| `setup_device` | Connect to WDA or return its exact build/launch commands |\n| `scan_ui` | Return visible interactive elements and device-point coordinates |\n| `describe_screen` | Return the visible accessibility hierarchy |\n| `device_action` | Perform one validated action |\n| `device_actions` | Perform a bounded sequence of validated actions |\n| `get_screenshot` | Create a temporary, unredacted screenshot and embedded preview |\n| `capture_design_snapshot` | Create a durable design handoff with redacted UI metadata |\n| `launch_app` | Activate an app by a known bundle ID |\n| `list_apps` | List installed apps on simulators |\n\nAlways call `get_execution_context` first. When multiple targets exist, pass the chosen `udid` explicitly to every subsequent tool.\n\n## Design snapshots\n\n`capture_design_snapshot` writes a versioned bundle below `~/.touchbridge/captures/`:\n\n```text\ncapture-directory/\n├── screen.png      full-resolution, unredacted pixels\n├── preview.png     downscaled, unredacted pixels\n├── ui.json         redacted accessibility metadata\n├── editor.json     normalized layers and sanitized editing intent\n└── manifest.json   design-snapshot@1 handoff contract\n```\n\nSee the [snapshot contract](docs/design-snapshot-capture.md) and [voice-to-design architecture](docs/voice-design-workflow.md).\n\n## Security and privacy\n\nTouchBridge stores local state beneath `~/.touchbridge/`:\n\n```text\n~/.touchbridge/\n├── captures/       durable design handoffs\n├── python/         isolated idb environment\n├── idb-companion/  local companion support\n├── wda-build/      pinned WebDriverAgent source and build data\n└── bin/            native accessibility helper\n```\n\n- The live viewer binds to `127.0.0.1`, not the public network.\n- Text entered with `input-text`, text keys, or text-key sequences is not echoed in MCP results or logs.\n- Sensitive accessibility values are redacted from `ui.json`, `editor.json`, manifests, and editing intents.\n- **Screenshot pixels are not redacted.** Temporary and durable PNGs can contain passwords, messages, health data, or other visible information.\n- Temporary screenshots use a randomized private directory. The returned full-resolution file remains until the caller deletes it.\n- Design snapshots are durable by design and remain until the user deletes their capture directory.\n- First-time setup downloads packages from GitHub, Homebrew, npm, and PyPI. Runtime device traffic remains local.\n- WebDriverAgent is a signed test runner installed on the device; stop its `xcodebuild` process when testing is complete.\n\nFor vulnerability reports, see [SECURITY.md](SECURITY.md).\n\n## Troubleshooting\n\n### Xcode sees the phone, but TouchBridge does not\n\nAn Xcode entry can represent a remembered device. TouchBridge requires a current CoreDevice tunnel or wired connection. Unlock the device, reconnect it with a data-capable cable, accept prompts, and rerun `--doctor`.\n\n### `No CoreDevice tunnel found`\n\nKeep the device unlocked and trusted. Confirm Developer Mode, then inspect `xcrun devicectl list devices`. A `disconnected` or `unavailable` tunnel cannot carry WDA traffic.\n\n### WebDriverAgent does not build\n\nOpen Xcode once, sign into an Apple ID, and allow automatic provisioning. If macOS requests keychain access during the build, choose **Always Allow** for the signing operation.\n\n### `get_execution_context` is ambiguous\n\nShut down unused simulators or select the intended target from `list_devices`, then pass that UDID explicitly.\n\n## Development\n\n```bash\ngit clone https://github.com/MarshallBear1/touchbridge-mcp.git\ncd touchbridge-mcp\nnpm ci\nnpm run check\nnpm audit --omit=dev\nnpm run smoke:package\n```\n\nCI runs the audit, typecheck, tests, and fresh-consumer package smoke test on macOS with Node 20.17 and Node 22.\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change. Keep device actions deterministic, bound externally supplied values, avoid logging screen content or typed text, and add regression tests for physical and simulator paths.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n"}