Apple IPSW & Firmware Restoration MCP Server 🍎⚡

The Model Context Protocol (MCP) server for Apple iOS, iPadOS, and macOS firmware management, real-time TSS signing status verification, hardware model resolution, and autonomous device restoration.

Designed specifically for AI coding assistants and autonomous agents (Claude Desktop, Cursor, Antigravity, Cline, OpenCode) to query, verify, download, and stage official Apple IPSW restore images without manual human intervention.

🚀 Why This MCP Server?

When AI agents are tasked with troubleshooting, recovering, or restoring iPhones and Apple devices, they hit three major roadblocks:

1. Unsigned Firmware Traps: Apple regularly closes TSS signing windows. Flashing an unsigned IPSW results in an immediate restoration failure.

2. Cryptic Hardware Identifiers: Users know their phone as "iPhone 15 Pro" or back-cover "A2848", but Apple firmware requires the board identifier ("iPhone16,1").

3. Multi-Gigabyte Context Bloat: Raw IPSW catalogs consume 50,000+ characters of context window.

ipsw-mcp-server solves this out-of-the-box:

• 🛡️ Real-Time TSS Signing Verification: Queries Apple TSS status via the official ipsw.me API v4 before taking any action.

• 🔍 Hardware Model Resolver: Translates regulatory A-numbers (A2848 ➔ iPhone16,1) and marketing names to restoration boards instantly.

• ⚡ Resumable Apple CDN Stream Downloader: Downloads 7–10 GB .ipsw images with HTTP Range resumption and automated SHA-1 integrity checks.

• 💾 Host Disk Budgeter: Validates host disk headroom before downloading massive firmware images to prevent host out-of-space crashes.

• 🧠 Context-Compacted Outputs: Built-in token compaction saves 80–95% context tokens, keeping agent interactions lightning-fast.

• 🔌 Zero External Dependencies: Built-in JSON-RPC 2.0 stdio server runs on standard Python 3.9+ without needing external packages.

Related MCP server: Apple Docs MCP

🏗️ Architecture

flowchart LR
    subgraph Host ["AI Agent Environment"]
        Agent["Autonomous Agent\n(Claude / Cursor / Antigravity)"]
        Config["MCP Client Config\n(JSON-RPC stdio)"]
    end

    subgraph MCP ["ipsw-mcp-server"]
        Server["server.py\n(FastMCP + Stdio Fallback)"]
        Compactor["token_compactor.py\n(Context Saver)"]
        Client["ipsw_client.py\n(IPSW.me API v4)"]
        Bridge["backup_bridge.py\n(MobileSync Inspector)"]
    end

    subgraph AppleCloud ["Apple Infrastructure"]
        TSS["Apple TSS / IPSW.me\n(Signing Status)"]
        CDN["Apple Production CDN\n(appldnld.apple.com)"]
    end

    subgraph DeviceBus ["Target Hardware"]
        USB["USB Bus / DFU Mode\n(idevicerestore / cfgutil)"]
        iPhone["Target Apple Device\n(iPhone / iPad / Mac)"]
    end

    Agent <--> Config
    Config <--> Server
    Server --- Compactor
    Server --- Client
    Server --- Bridge
    Client <--> TSS
    Client --> CDN
    Server -. Command Pipeline .-> USB
    USB --> iPhone

⚡ Quick Start & Configuration

1. Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "apple-ipsw": {
      "command": "python3",
      "args": ["/path/to/ipsw-mcp-server/server.py"],
      "env": {
        "IPSW_DOWNLOAD_DIR": "~/Downloads/IPSW"
      }
    }
  }
}

2. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "apple-ipsw": {
      "command": "python3",
      "args": ["/path/to/ipsw-mcp-server/server.py"]
    }
  }
}

3. VS Code / Cline / Roo Code / Antigravity

Configure standard stdio transport:

• Command: python3

• Arguments: ["/path/to/ipsw-mcp-server/server.py"]

🛠️ Exposed MCP Tools

💡 Example Agent Prompts

Once configured in your AI agent, you can ask natural language questions:

• "What iOS versions are currently signed for my iPhone 14 Pro (A2650)?"

• "Download the latest signed IPSW for iPhone15,2 to my downloads folder and verify its SHA1 checksum."

• "Check if my local iPhone backup can be restored onto iOS 18.1.1 without triggering an OS upgrade."

• "Do I have enough disk space on this Mac to stage an IPSW restore for my connected iPad?"

• "Generate an idevicerestore command sequence to re-flash this iPhone in DFU mode."

🧪 Testing & Verification

Run the built-in self-test (zero configuration required):

python3 server.py --selftest

Run comprehensive offline unit test suite:

pytest -v

📦 Zero-Dependency Architecture

Unlike MCP servers that require sprawling node packages or complex Docker setups, ipsw-mcp-server is written in clean, modern Python using the standard library.

• Works seamlessly with python3 or uv.

• Compatible with Python 3.9, 3.10, 3.11, 3.12, and 3.13.

• Cross-platform support across macOS, Windows, and Linux.

🔗 Related Projects

• ios-system-data-cleaner: Autonomous zero-lockout iOS storage reclamation engine and cache bloat purger.

• IPSW.me: Community Apple firmware downloads API.

• libimobiledevice: Cross-platform protocol library to communicate with iOS devices natively.

📄 License

MIT License © 2026 Vladislav Ekimtcov.