ipsw-mcp-server
README.md
# Apple IPSW & Firmware Restoration MCP Server 🍎⚡
[](https://github.com/VladislavEkimtcov/ipsw-mcp-server/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[-brightgreen.svg)](#zero-dependency-architecture)
> **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.
---
## 🏗️ Architecture
```mermaid
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`:
```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`)
```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
| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `search_apple_devices` | `query`, `product_family`, `limit`, `compact` | Search Apple hardware to find internal board identifiers (e.g. `iPhone16,1`, `Mac15,3`). |
| `resolve_apple_model_number` | `model_number` | Convert back-case `Axxxx` numbers (`A2848`) to restoration identifiers. |
| `get_signed_ipsw_firmwares` | `identifier`, `include_unsigned`, `compact` | Query active Apple TSS signing status. Returns builds that can be restored today. |
| `get_ipsw_build_metadata` | `identifier`, `buildid` | Fetch Apple CDN URL, SHA-1 checksum, file size, and upload timestamp. |
| `list_ipsw_by_os_version` | `version`, `signed_only`, `device_family` | List firmware restoration images across all Apple models for a given iOS/iPadOS release. |
| `download_ipsw_for_restore` | `identifier`, `buildid`, `output_dir` | Stream-download official Apple `.ipsw` with HTTP Range resumption and SHA-1 verification. |
| `verify_downloaded_ipsw` | `file_path`, `expected_sha1` | Compute SHA-1/MD5 checksums and emit ready-to-run `idevicerestore` commands. |
| `detect_connected_apple_devices` | *(none)* | Scan USB bus for connected iPhones/iPads in Normal, Recovery, or DFU mode. |
| `match_backup_to_ipsw` | `udid`, `backup_path` | Match local MobileSync backups with signed IPSWs to verify forward compatibility. |
| `check_restore_disk_budget` | `udid`, `target_firmware_size_gb` | Audit host disk buffer (download + 12 GB staging + safety margin) before starting. |
| `generate_restore_pipeline` | `udid`, `target_buildid` | Generate validated step-by-step restoration command sequence for this specific device. |
---
## 💡 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):
```bash
python3 server.py --selftest
```
Run comprehensive offline unit test suite:
```bash
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**](https://github.com/VladislavEkimtcov/ios-system-data-cleaner): Autonomous zero-lockout iOS storage reclamation engine and cache bloat purger.
* [**IPSW.me**](https://ipsw.me): Community Apple firmware downloads API.
* [**libimobiledevice**](https://libimobiledevice.org/): Cross-platform protocol library to communicate with iOS devices natively.
---
## 📄 License
MIT License © 2026 Vladislav Ekimtcov.