DEV Community

Cover image for Thumbly: connect an MCP agent to a real iPhone from your Mac
Timur Catakli
Timur Catakli

Posted on

Thumbly: connect an MCP agent to a real iPhone from your Mac

#mcp #opensource #showdev #automation

I'm the maker of Thumbly, a free, open-source Mac app that lets MCP agents see and operate a real iPhone. Version 0.1.0 is available now.

The short demo below shows Claude Code using it.

What the agent can do

Thumbly exposes native screenshots, taps, swipes, long presses, text entry, hardware buttons, app launching and device information. A Python SDK is also available for scripts.

The phone connects to your Mac over USB, or Wi-Fi after the first USB pairing. The service talks to Apple's CoreDevice services through pymobiledevice3. No jailbreak is required.

Where control lives

There are three parts to the flow:

MCP client → Thumbly service on the Mac → iPhone
                       ↑
               Thumbly Mac app
           approve · inspect · pause
Enter fullscreen mode Exit fullscreen mode

Each new client waits for approval in the Mac app. You can inspect the activity log and use Pause to stop AI access. This is client approval; it does not mean the owner confirms each individual tap.

The device connection runs through your Mac without a cloud relay. Your choice of agent still matters: a cloud-backed agent can receive the screenshots returned to its MCP client.

Try it with Claude Code

You'll need macOS 14 or later, an iPhone running iOS 17.4 or later, a USB data cable, and Apple's Command Line Tools.

  1. Install Thumbly using the instructions on the project site. The installer builds the Mac app and sets up the Python service.
  2. Connect and unlock the iPhone, then tap Trust.
  3. Enable Developer Mode under Settings → Privacy & Security and restart the phone. The initial developer disk image setup can take a few minutes.
  4. Add the local MCP endpoint to Claude Code: 
claude mcp add --transport http thumbly http://127.0.0.1:8771/mcp
Enter fullscreen mode Exit fullscreen mode
  1. In Claude Code, open /mcp, select Thumbly and authenticate. Approve that client in the Mac app's Access screen.
  2. Start with a small task you can verify, such as opening Notes and writing a test note. Watch the activity log as the agent works.

Other MCP clients can connect too. Claude.ai and ChatGPT require the separate remote-access setup documented in the repository.

For contributors

The repository contains the SwiftUI Mac app, Python service, Python SDK and documentation. The Mac app and SDK use Apache-2.0; the device service uses GPL-3.0 because it links to pymobiledevice3.

There is also a simulated-device mode for development without an iPhone:

thumbly serve --simulate
Enter fullscreen mode Exit fullscreen mode

This is an early release. Feedback on pairing, client authentication and workflows that fail is particularly useful. When reporting a problem, include your macOS and iOS versions, USB or Wi-Fi, and the steps that reproduced it.

What phone workflow would you try first?

Disclosure: this article was prepared with AI assistance using Thumbly's public documentation.

Top comments (0)