ios-icon-mcp

Organize an iPhone home screen from any MCP-compatible AI client. Move apps and web clips, create folders, rearrange pages, and inspect widget-aware text layouts with natural language.

No jailbreak, device supervision, or Apple Configurator is required.

中文版 README

Warning: This project uses private iOS APIs through pymobiledevice3. Compatibility can change with iOS updates. Use the preview and backup features before writing.

Features

• Read apps, folders, web clips, and widgets, including localized names and bundle IDs.

• Render pages as text grids using the device's reported rows and columns.

• Edit a saved layout or make a direct change on the device.

• Create folders, including folders with multiple pages.

• Preview changes by default before applying a layout file.

• Refuse unknown IDs, accidental app removal, over-capacity pages, and widget displacement.

• Back up automatically before every write and verify the resulting layout and widgets.

• Restore complete backups, with a preview and a fresh safety backup.

Related MCP server: astrolabe

Requirements

• macOS with its built-in usbmuxd.

• One iPhone connected over USB, unlocked, and trusted by the Mac.

• uv, which provides the uvx command.

The MCP server needs Python 3.10 or newer; uvx handles the Python environment and dependencies.

Install

Add this to your MCP client's configuration:

{
  "mcpServers": {
    "ios-icon": {
      "command": "uvx",
      "args": ["ios-icon-mcp"]
    }
  }
}

Restart the MCP client after changing its configuration. The first run downloads the package into an isolated environment.

To run directly from GitHub instead:

{
  "mcpServers": {
    "ios-icon": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/huangzheng2016/ios-icon-mcp",
        "ios-icon-mcp"
      ]
    }
  }
}

To upgrade the cached PyPI package, run uvx --refresh ios-icon-mcp or restart the client with that command once.

Quick start

Connect and unlock the iPhone, then ask your AI client:

• “Show my home screen as a text grid.”

• “Export every app with its name and bundle ID.”

• “Save the current layout, put my music apps in a folder, and preview the change.”

• “Move this app to page 2 without changing anything else.”

For a batch edit, the intended flow is:

1. save_layout creates a workspace snapshot.

2. move_icon, swap_icons, or create_folder edits that file.

3. apply_icon_layout previews the complete diff by default.

4. After reviewing the result, call it with dry_run=false to write.

5. Check verified in the response. Backups are created automatically.

Direct *_on_device tools are intended for small changes and write immediately unless dry_run=true is supplied.

Layout format

A layout is a JSON array. Index 0 is the Dock; subsequent arrays are home screen pages. Strings are app bundle IDs or web clip URLs. A folder is an array whose first item is its name.

[
  ["com.apple.mobilephone", "com.apple.MobileSMS"],
  [
    "com.apple.mobilesafari",
    ["Social", "com.example.chat", "com.example.social"],
    ["Multi-page folder", ["com.example.one"], ["com.example.two"]]
  ]
]

The IDs above only illustrate the syntax. Use IDs from get_icon_layout or export_icon_detail for a real edit.

• Flat folder form: ["Folder", "app.one", "app.two"].

• Multi-page folder form: ["Folder", ["app.one"], ["app.two"]].

• Widgets are deliberately omitted from this editable representation and merged from the current device state during writes.

Tools

apply_icon_layout defaults to dry_run=true. restore_backup also defaults to dry_run=true; a real restore requires dry_run=false.

Safety and limitations

• No silent app loss. If a layout omits existing apps or web clips, writing is refused. For intentional removal from the home screen, set allow_remove=true. This never uninstalls the app.

• No unknown IDs. Only apps and web clips already present in the current home screen state can be rearranged. Adding arbitrary items from App Library is not supported.

• Widgets are protected, not editable. The server cannot create or configure widgets. A layout that would move a widget to another page or change its estimated grid position is refused. Keep the widget's page and the number of icons before it unchanged.

• Capacity includes widgets. Limits come from the device rather than a hard-coded 4×6 grid. Validation also simulates widget occupancy.

• Positions are estimates. Row and column values are inferred from icon order and widget sizes; they are not coordinates supplied by iOS.

• Backups contain personal layout data. They stay in the local, Git-ignored workspace/ directory. Review files before sharing them.

• One device at a time. Connect only the iPhone you intend to modify.

Development

git clone https://github.com/huangzheng2016/ios-icon-mcp.git
cd ios-icon-mcp
uv sync --locked
uv run python -m compileall -q server.py
uvx --from ruff==0.17.1 ruff check server.py
uv build
uvx twine check dist/*

CI runs offline checks across supported Python versions and builds the wheel and source distribution. GitHub releases are published to PyPI with Trusted Publishing (OIDC), without a stored PyPI password or long-lived API token.

License

MIT