flutter-ios-bridge-mcp

Ship Flutter apps to iOS from Windows or Linux — no Mac needed.

An MCP server that gives your AI assistant (Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf…) the tools to build, sign, test and upload iOS apps. It connects your machine to the Apple parts of the toolchain:

Install

pipx install flutter-ios-bridge-mcp                                              # from PyPI
pipx install git+https://github.com/guru-prasath-j/flutter-ios-bridge-mcp.git   # latest from GitHub

# optional: USB iPhone support
pipx inject flutter-ios-bridge-mcp pymobiledevice3

Then:

flutter-ios-bridge-mcp init       # writes a commented config.toml (or use env vars)
flutter-ios-bridge-mcp status     # shows what is configured
flutter-ios-bridge-mcp doctor path/to/flutter_app   # iOS audit, no AI needed

Connect it to your MCP client

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/… on Linux):

{
  "mcpServers": {
    "flutter-ios-bridge": {
      "command": "flutter-ios-bridge-mcp",
      "env": {
        "FIB_PROJECT_PATH": "C:/Users/me/code/my_app",
        "GITHUB_TOKEN": "github_pat_...",
        "ASC_KEY_ID": "ABC123XYZ",
        "ASC_ISSUER_ID": "00000000-0000-0000-0000-000000000000",
        "ASC_PRIVATE_KEY_PATH": "C:/keys/AuthKey_ABC123XYZ.p8"
      }
    }
  }
}

Claude Code: claude mcp add flutter-ios-bridge -- flutter-ios-bridge-mcp

VS Code / Cursor (.vscode/mcp.json / .cursor/mcp.json): same command + env shape.

No pipx on PATH? Use "command": "pipx", "args": ["run", "flutter-ios-bridge-mcp"].

Configuration

Environment variables win over config.toml (%APPDATA%\flutter-ios-bridge\config.toml on Windows, ~/.config/flutter-ios-bridge/config.toml elsewhere; override with FIB_CONFIG).

Signing material created by the tool lives in ~/.flutter-ios-bridge/signing/ (private keys are chmod 600). Back it up — the certificate private key never leaves your machine except as an encrypted GitHub secret.

The zero-Mac path to TestFlight

Ask your assistant "Ship my app to TestFlight" (or use the built-in ship_to_testflight prompt). Under the hood:

1. ios_doctor → fix bundle id (com.example.* is rejected), missing permission strings for your plugins, deployment target / Podfile mismatch, icon alpha channel…
2. ci_generate_workflow → commit & push .github/.
3. ci_trigger_build(build_type="unsigned-ipa") → ci_wait_for_run → on failure ci_get_logs pulls the exact Xcode/CocoaPods errors so the assistant can fix them.
4. Create the app record once in App Store Connect (Apple's API can't create apps).
5. signing_quick_setup(profile_kind="app-store") — CSR → Apple Distribution certificate → .p12 → App Store profile → GitHub secrets. All from Windows/Linux.
6. ci_trigger_build(build_type="signed-ipa", testflight=true).
7. testflight_builds → testflight_distribute (export compliance + beta groups).

Testing on a real iPhone without a Mac

• Ad-hoc: asc_register_device (reads the UDID over USB) → signing_quick_setup(profile_kind="ad-hoc") → ci_trigger_build(build_type="signed-ipa", export_method="ad-hoc") → ci_download_artifacts → device_install_app → device_syslog for crash logs.
• Free Apple ID: build unsigned-ipa and sideload with Sideloadly / AltStore (7-day signature).
• Simulator: needs macOS; with a remote Mac use mac_run_on_simulator + mac_screenshot.

Tools

Costs and limits

• GitHub-hosted macOS minutes are free on public repos; private repos consume your Actions minutes at a 10× rate (check GitHub's current pricing). A clean Flutter iOS build takes roughly 8–20 minutes.
• Publishing to TestFlight/App Store requires a paid Apple Developer Program membership.
• Apple caps the number of distribution certificates; signing_quick_setup reuses the one it created, and asc_revoke_certificate frees a slot.
• Windows USB access needs Apple's driver (install Apple Devices from the Microsoft Store, or iTunes); Linux needs usbmuxd.

Security

• Tokens and keys are read from env/config only; nothing is sent anywhere except GitHub and Apple APIs (and your own Mac over SSH).
• GitHub secrets are encrypted locally with the repo's public key (libsodium sealed box) before upload.
• The CI workflow creates a throwaway keychain per run and deletes it afterwards.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]" && pytest
npx @modelcontextprotocol/inspector flutter-ios-bridge-mcp   # poke at the tools

MIT © Guruprasath J