Claude Code for iOS development: a setup that builds, runs and checks your app

Claude Code writes Swift well, but out of the box it does not know your scheme, cannot see the simulator and does not know which SwiftUI APIs your team considers current. A useful iOS setup adds four layers: project instructions, a build/run tool, a way to see the UI, and Swift-specific skills. Each step below links to the official docs or the project README it comes from.

What you need

• A Mac with Xcode (the iOS Simulator only runs on macOS).

• Claude Code (terminal, IDE extension or the Desktop app).

• A project that already builds and runs in Xcode by hand. Fix signing and scheme problems first; the agent uses the same toolchain.

Step 1: Write project instructions (CLAUDE.md or AGENTS.md)

Claude Code starts every session with a fresh context window and loads CLAUDE.md files as persistent instructions (Claude Code memory docs). Put the project file at ./CLAUDE.md or ./.claude/CLAUDE.md. Running /init generates a first version from your codebase. If your repo already has an AGENTS.md for other agents, Claude Code v2.1.277+ reads it when no CLAUDE.md exists; or add a CLAUDE.md containing @AGENTS.md to import it.

The docs recommend keeping each file under about 200 lines and writing instructions concrete enough to verify. For an iOS app that typically means:

# MyApp
- Workspace: MyApp.xcworkspace, scheme: MyApp, simulator: iPhone 17
- Minimum deployment target: iOS 18. Swift 6 language mode, strict concurrency.
- UI: SwiftUI with @Observable models. No new UIKit screens.
- Tests: Swift Testing (`import Testing`) for new tests.
- Before finishing: build the app and run the MyAppTests scheme.

(The values above are an example; replace them with your project's.) For rules that only apply to some files, Claude Code supports .claude/rules/*.md with a paths: glob such as "**/*.swift".

Step 2: Give Claude a build and run tool (MCP)

Claude Code connects to tools through MCP. Local servers are added with claude mcp add <name> -- <command>; --scope project writes a shared .mcp.json your team can commit (Claude Code MCP docs).

Option A, MobileBuildMCP (formerly XcodeBuildMCP). Builds, runs and tests on simulators and devices without Xcode open. From the official client docs:

claude mcp add MobileBuildMCP -- npx -y mobilebuildmcp@latest mcp

Then run mobilebuildmcp setup in the project root to store your project, scheme and default simulator in .mobilebuildmcp/config.yaml (setup docs). Details: our MobileBuildMCP setup guide.

Option B, Apple's Xcode Tools. Xcode 26.3+ ships xcrun mcpbridge, which talks to the running Xcode (build, tests, SwiftUI preview rendering, Apple doc search). Enable it in Xcode → Settings → Intelligence → Model Context Protocol. Our catalog entry lists the Claude Code command: claude mcp add --transport stdio xcode -- xcrun mcpbridge (entry, Apple docs).

Check the connection with claude mcp list or /mcp inside a session.

Step 3: Let Claude see the app

An agent that only reads build logs cannot tell whether a screen looks right. Three options:

The Desktop pane needs Claude Desktop v1.24012.0 or later and Xcode with the iOS platform installed; it uses whichever Xcode xcode-select points at. From the CLI, Claude reaches the simulator through computer use instead.

To add iOS Simulator MCP, per its README:

claude mcp add ios-simulator npx ios-simulator-mcp

Step 4: Add Swift and SwiftUI skills

Skills are folders with a SKILL.md that Claude loads when relevant (skills docs). For iOS, community skills encode current API guidance so Claude stops reaching for deprecated patterns. Popular picks in the catalog:

Install only what matches your stack; every loaded skill and MCP tool costs context.

A working loop

With the layers in place, a typical request looks like: "Add a settings screen with a toggle for notifications. Build, run it in the simulator, and show me the screen." Claude reads CLAUDE.md for the scheme and conventions, writes SwiftUI following the skill, builds through MCP, fixes compiler errors, launches the app and checks the screen through the simulator tool or pane.

Use cases where this setup pays off:

• Compiler-error loops: Claude reads structured build errors from the MCP server and iterates without you copying logs.

• UI regressions: ask Claude to re-check a screen after a refactor.

• Swift 6 migration: a concurrency skill plus build feedback.

• Release chores: add an App Store Connect MCP server for TestFlight and metadata.

Common problems

• The server never connects: run claude mcp get <name>; failure details include the error since recent versions (MCP docs).

• Builds time out: large projects take time; a per-server timeout (milliseconds) in .mcp.json raises the limit for that server.

• mcpbridge not found: point xcode-select at the full Xcode app, not the Command Line Tools (Cursor's Xcode docs describe the fix).

• Claude ignores your conventions: run /context to confirm the CLAUDE.md loaded, and make rules more specific.