Let AI Build, Test, and Debug Your Bazel iOS App 🚀

A practical guide to XcodeBazelMCP, an MCP server and CLI for Bazel-based Apple development across builds, tests, simulators, devices, and debugging.

TL;DR

• XcodeBazelMCP exposes Bazel-based Apple workflows through an MCP server and a CLI.
• It targets iOS, macOS, tvOS, watchOS, visionOS, and Swift Package Manager workflows.
• The useful mental model is: workspace first, target second, workflow third.
• The tool is strongest when you want repeatable build, run, test, simulator, device, and debugging operations from an AI-capable client.
• Treat it as automation infrastructure, not magic. Your Bazel graph, Xcode install, simulator state, and device setup still matter.

Hook

Most iOS teams do not lose time because they forgot how to build an app. They lose time in the seams: finding the right Bazel target, booting the right simulator, passing the correct flags, rerunning one failing test, grabbing logs, installing on a physical device, or explaining all of that context to an AI coding tool.

That gap gets wider in Bazel-based Apple projects. Xcode is no longer the only source of truth. Your app is a target, your build graph is a queryable model, and “run the app” often means a chain of commands.

XcodeBazelMCP is interesting because it turns that chain into MCP tools and CLI commands. It gives AI clients a structured way to build, test, run, debug, inspect, and operate Apple workflows instead of guessing shell commands. The result is not a replacement for understanding Bazel. It is a cleaner control plane for developers who already live in complex Apple build systems.

Try Now!

[embed]GitHub - XcodeBazelMCP/XcodeBuildMCP: MCP server and CLI for Bazel-based Apple platform development… MCP server and CLI for Bazel-based Apple platform development - tools for iOS, macOS, tvOS, watchOS, visionOS builds…github.com

Table of Contents

1. What XcodeBazelMCP Is
2. Why Bazel iOS Workflows Need Tooling
3. Installing and Wiring the MCP Server
4. Workspace Configuration and Profiles
5. Build, Run, Test, and Debug Workflows
6. Simulator, Device, and Deep Link Operations
7. Adoption Checklist and Trade-Offs

Summary

XcodeBazelMCP is a Model Context Protocol server and CLI for Bazel-based Apple platform development. The repository describes it as shipping 112 tools across 19 workflow categories, covering iOS, macOS, tvOS, watchOS, visionOS, and Swift Package Manager workflows.

That framing matters. This is not “another Xcode wrapper.” It is a tool surface for operations that Apple platform engineers already perform every day: build, run, test, discover targets, manage simulators, interact with devices, collect logs, and debug with LLDB.

Takeaway: XcodeBazelMCP is best understood as a structured automation layer around Bazel Apple workflows.

What XcodeBazelMCP Is

The repository presents XcodeBazelMCP as both an MCP server and a CLI. That dual shape is important.

As an MCP server, it gives AI-capable clients a set of structured tools. Instead of asking an assistant to invent a bazel command from memory, the assistant can call a tool that already knows about the workspace, target, simulator, workflow category, and expected output.

As a CLI, it remains useful outside the AI client. You can run health checks, discover targets, query dependencies, build, run, test, scaffold projects, and configure defaults directly from a terminal. The README lists workflows for build, test, simulator management, app lifecycle, capture, UI automation, deep links, physical devices, LLDB, macOS, tvOS, watchOS, visionOS, Swift Package Manager, project discovery, scaffolding, session management, daemon operations, and updates.

The strongest use case is not a small single-target app. It is a multi-target, Bazel-backed Apple workspace where developers frequently ask:

• Which target should I run?
• Which simulator is booted?
• Can I rerun only this test?
• Can I inspect the Bazel graph?
• Can I install this build on a real device?
• Can the assistant collect logs before suggesting a fix?

That is where MCP becomes useful. It gives the assistant affordances instead of vibes.

Pro Tip: Treat MCP tools as typed operations over your workflow. The better your workspace defaults are, the less your AI client needs to infer.

Takeaway: XcodeBazelMCP gives AI tools and humans the same operational vocabulary for Bazel Apple development.

Why Bazel iOS Workflows Need Tooling

Bazel-based iOS projects tend to trade Xcode convenience for scale, reproducibility, and explicit build graph control. That trade is often worth it, but it creates friction.

A normal Xcode project has visible schemes. A Bazel workspace has labels. A normal simulator run may be one button. A Bazel simulator run may involve building a target, locating the app bundle, installing it, launching it, passing arguments, and collecting logs.

XcodeBazelMCP compresses those workflows into repeatable tool calls and commands. The README explicitly lists build and run support for simulators and physical devices, test and coverage support, simulator lifecycle management, physical-device operations via xcrun devicectl, LLDB debugging, UI automation, deep links, and project discovery.

That does not remove the need to understand Bazel. You still need valid targets, correct BUILD files, and a healthy Apple toolchain. But it moves repeated orchestration into one place.

Example: instead of manually stepping through “query target → build → boot simulator → install → launch → open URL,” you can model that as a workflow.

A mini-case:

1. Query for candidate app targets.
2. Build the selected simulator target.
3. Boot an iPhone simulator.
4. Install and launch the app.
5. Open a deep link into the target feature.
6. Capture logs or a screenshot when the flow fails.

This is especially valuable when debugging flows like login callbacks, push notification handling, or feature flags. The interesting part is not the command itself. It is the sequence.

Gotcha: MCP does not fix an ambiguous Bazel workspace. If multiple targets look plausible, your assistant may still need clear defaults.

Takeaway: Bazel iOS workflows benefit from tooling because the hard part is orchestration, not individual commands.

Installing and Wiring the MCP Server

The repository documents a global npm installation and an npx path. It requires macOS with Xcode installed, Node.js 18 or newer, Bazel or Bazelisk on PATH, and a Bazel workspace configured through an environment variable, config file, CLI flag, or MCP tool.

https://www.npmjs.com/package/xcodebazelmcp

npm install -g xcodebazelmcp

This is the quickest persistent install path. It gives you the xcodebazelmcp binary from the package. The package metadata identifies the npm package name as xcodebazelmcp and exposes xcodebazelmcp as a binary.

npx -y xcodebazelmcp mcp

This form is better when you want to avoid a global install. It starts the MCP server directly through npx.

npx -y xcodebazelmcp setup

The setup command is documented as an interactive quick start. Use it when onboarding a workspace or validating that local prerequisites are in place.

npx -y xcodebazelmcp init

The README describes this command as installing agent skills for Cursor or Codex.

The MCP configuration is straightforward:

{
  "mcpServers": {
    "XcodeBazelMCP": {
      "command": "npx",
      "args": ["-y", "xcodebazelmcp", "mcp"],
      "env": {
        "BAZEL_IOS_WORKSPACE": "/path/to/your/ios-workspace"
      }
    }
  }
}

The important part is not the JSON shape. It is the workspace boundary. The server needs to know which Bazel workspace it operates on. Without that, every downstream workflow becomes fragile.

Why this design works:

• The MCP client gets a stable command entry point.
• The workspace is explicit.
• The same binary supports interactive setup, CLI workflows, and MCP serving.
• Teams can check in documented setup instructions without coupling everyone to one editor.

Trade-offs:

• Node.js becomes part of the local Apple development toolchain.
• Local machine state still matters: Xcode version, simulator availability, Bazelisk config, and device pairing.
• Global installs can drift, while npx can be more reproducible but slower to start.

Testability notes:

• Start with xcodebazelmcp doctor.
• Validate that Bazel or Bazelisk is on PATH.
• Run a target discovery command before attempting a build.
• Test one simulator path before adding device workflows.
• Keep setup instructions deterministic for new engineers.

Takeaway: Installation is simple, but reliable usage depends on making the workspace explicit.

Workspace Configuration and Profiles

XcodeBazelMCP resolves the workspace through several layers. The README lists the order of precedence: runtime MCP tool or CLI defaults, CLI workspace flag, BAZEL_IOS_WORKSPACE, config file, and finally process.cwd().

That hierarchy is exactly what you want in a developer tool. Local overrides should be easy. Team defaults should still exist. Fallback behavior should be predictable.

npx -y xcodebazelmcp mcp --workspace /path/to/your/ios-workspace

A workspace flag is explicit and easy to debug. It is a good fit for local experiments or editor-specific configuration.

For repeated workflows, profiles are more interesting:

profiles:
  app:
    target: '//app:app'
    platform: simulator
    buildMode: debug
  mac:
    target: '//mac:mac'
    platform: macos

Then switch at runtime:

xcodebazelmcp set-defaults --profile app

This gives teams a clean place to encode “known good” defaults. A profile can define the default app target, platform, and build mode. That matters when your Bazel workspace has many apps, extensions, test bundles, and internal tools.

A practical structure:

1. Create one profile for the main iOS app.
2. Create one profile for each high-traffic platform target.
3. Keep debug defaults fast.
4. Avoid hiding production-specific flags in local profiles.
5. Document target ownership near the Bazel labels.

Gotcha: Profiles are powerful, but stale profiles are worse than no profiles. Update them when targets move, split, or get renamed.

Extension points:

• Add profiles for feature apps or sample apps.
• Use separate profiles for simulator and device workflows.
• Keep CI-oriented Bazel flags outside local developer defaults unless they are required for correctness.
• Pair profiles with onboarding docs.

Testability notes:

• Add a “profile smoke test” to onboarding: switch profile, discover target, build target.
• Ensure a new machine can run the default profile without private local paths.
• Use small targets for initial validation before running large app builds.

Takeaway: Workspace profiles turn repeated Bazel context into reusable developer intent.

Build, Run, Test, and Debug Workflows

The README gives concrete CLI examples for health checks, discovery, query, simulator builds, simulator runs, device runs, tests, macOS workflows, Swift Package Manager, scaffolding, and config inspection.

# Health check
xcodebazelmcp doctor

# Discover & query
xcodebazelmcp discover --scope //Apps/... --kind apps
xcodebazelmcp query 'deps(//app:app)'

# Build & run (simulator)
xcodebazelmcp build //app:app --debug --simulator
xcodebazelmcp run //app:app --simulator-name "iPhone 16 Pro"

# Build & run (device)
xcodebazelmcp device-run //app:app --device-name "iPhone"
xcodebazelmcp device-screenshot output.png --device-name "iPhone"
xcodebazelmcp device-log-start --device-name "iPhone"

# Test
xcodebazelmcp test //tests:UnitTests --filter "SomeTest/testCase" --stream

# macOS
xcodebazelmcp macos-build //mac:mac --debug
xcodebazelmcp macos-run //mac:mac

# Swift Package Manager
xcodebazelmcp spm-build --path ./MyPackage
xcodebazelmcp spm-test --filter "MyTests/testExample"

# Scaffold
xcodebazelmcp new ios_app MyNewApp --bundle-id com.example.MyNewApp

# Config
xcodebazelmcp defaults
xcodebazelmcp set-defaults --target //app:app --simulator-name "iPhone 16 Pro"
xcodebazelmcp workflows

The sequence tells you how the tool expects to be used.

Start with doctor. That prevents you from debugging a target when the actual problem is the local environment.

Then discover. Bazel labels are precise, but humans often remember partial names. Discovery reduces target guessing.

Then build or run. The simulator path is explicit: build for simulator, then run on a named simulator.

Then test with filters. For intermediate and advanced iOS developers, filtered test execution matters. It reduces feedback loops when you are iterating on one failing unit or UI test.

Then collect logs, screenshots, or run device workflows when the issue leaves the simulator.

Why this design works:

• It mirrors the real development loop.
• It supports both broad discovery and narrow execution.
• It keeps device operations separate from simulator operations.
• It gives AI tools command-shaped capabilities with clear parameters.

Trade-offs:

• The CLI examples assume your Bazel targets and platform rules are already valid.
• Test filtering depends on how your test runner names tests.
• Streaming output is useful, but noisy logs can overwhelm an AI client.
• Device workflows require more local setup than simulator workflows.

Testability notes:

• Use --filter for failing tests before running the full suite.
• Prefer simulator workflows for deterministic feature testing.
• Use physical devices for hardware, entitlement, iOS version, or CoreDevice-specific behavior.
• Capture logs and screenshots as artifacts when asking an AI assistant to diagnose a failure.

Pro Tip: Before asking an AI assistant to “fix the test,” ask it to run the smallest filtered test command and inspect the output.

Mini-case: deep link debugging

Imagine a checkout feature fails only when opened from a campaign URL.

A useful flow is:

1. Build and run the app on a known simulator.
2. Open the deep link into the checkout route.
3. Capture logs while the route resolves.
4. Take a screenshot after navigation completes.
5. Rerun the focused test or UI automation path.

That flow surfaces navigation bugs, missing route registration, bad launch state, and simulator-only assumptions.

Takeaway: XcodeBazelMCP is most valuable when you use it as a repeatable loop: diagnose, discover, execute, inspect.

Simulator, Device, and Deep Link Operations

The repository lists simulator management, app lifecycle, capture, UI automation, and deep link workflows as first-class categories. It also lists physical-device support through xcrun devicectl, including listing, pairing, installing, launching, terminating, screenshots, and log capture.

That breadth matters because modern iOS bugs rarely stay inside “build failed.” Many failures are stateful:

• The simulator is booted but dirty.
• The wrong app is installed.
• A previous login session masks the bug.
• The push payload is malformed.
• The deep link opens the wrong route.
• Device logs reveal an entitlement or provisioning issue.

XcodeBazelMCP also documents iOS 17+ device notes. According to the README, Apple replaced lockdownd and usbmuxd with CoreDevice-related infrastructure starting in iOS 17 and macOS 15. The README says xcrun devicectl is the reliable CLI for device operations, while screenshots require pymobiledevice3 with tunneld running because there is no devicectl screenshot subcommand.

That is a real-world gotcha. Device automation is not just “simulator automation with a cable.” It has different tools, different permissions, and different failure modes.

A practical simulator flow:

1. Boot the target simulator.
2. Erase or reset state when testing onboarding.
3. Build and install the app.
4. Launch with a known target.
5. Open a deep link.
6. Capture a screenshot and logs.

A practical device flow:

1. Confirm device visibility.
2. Pair or trust the device when needed.
3. Build for device.
4. Install and launch.
5. Start log capture.
6. Use screenshots only after required dependencies are configured.

Trade-offs:

• Simulator automation is faster and easier to reset.
• Physical devices expose signing, entitlement, hardware, OS, and performance realities.
• Deep links are excellent smoke tests, but they can hide missing preconditions.
• UI automation can validate flows, but accessibility identifiers must be stable.

Testability notes:

• Add accessibility identifiers for critical UI automation paths.
• Keep deep link routes deterministic.
• Make logged-out and logged-in flows separately testable.
• Capture screenshots at route boundaries.
• Treat push payloads as fixtures.

Takeaway: Simulator and device support make XcodeBazelMCP useful beyond compilation; it can exercise real app behavior.

Adoption Checklist and Trade-Offs

Use this pattern when your team already has Bazel-based Apple workflows and wants a cleaner interface for humans and AI clients.

Implementation steps:

1. Verify prerequisites. Confirm macOS, Xcode, Node.js 18+, and Bazel or Bazelisk are installed.
2. Install or run with npx. Pick global installation for convenience or npx for lower setup friction.
3. Configure the workspace. Prefer an explicit workspace path through MCP config, CLI flag, or environment variable.
4. Run doctor. Fix environment problems before debugging app targets.
5. Discover targets. Use discovery before hardcoding labels into docs or prompts.
6. Create profiles. Add defaults for common app, macOS, simulator, and device workflows.
7. Smoke test the loop. Build, run, test, open a deep link, capture logs, and take a screenshot.
8. Document team usage. Add examples for the most common app targets and test bundles.
9. Keep workflows scoped. Enable only the workflow categories your team actually uses.
10. Review failures as infrastructure signals. A flaky MCP flow often points to simulator state, device setup, or Bazel target drift.

When not to use it:

• Your app is a simple Xcode-only project.
• Your team does not use Bazel.
• You only need occasional manual builds.
• Your local environments are too inconsistent to automate yet.

Where it shines:

• Large iOS apps with many Bazel targets.
• Teams using AI coding clients.
• Repeated simulator and device workflows.
• Debugging flows that need logs, screenshots, deep links, or focused tests.
• Multi-platform Apple repositories.

One architectural comparison is helpful. In SwiftUI navigation, a NavigationPath works best when destinations are explicit and serializable. XcodeBazelMCP follows a similar principle for build workflows: make operations explicit, parameterized, and repeatable. Do not ask the assistant to infer your path through the app or build graph. Give it tools that encode the path.

Takeaway: Adopt XcodeBazelMCP as workflow infrastructure, then layer AI assistance on top.

9) FAQ

Is XcodeBazelMCP only for iOS?

No. The README describes support for iOS, macOS, tvOS, watchOS, visionOS, and Swift Package Manager workflows.

Do I need Bazel to use XcodeBazelMCP?

Yes for the core Bazel Apple workflows. The documented requirements include Bazel or Bazelisk on PATH and a Bazel workspace configured through one of the supported mechanisms.

Can it run tests with filters?

Yes. The README shows a test command using --filter and --stream, which is useful for focused test iteration.

Does it support physical iOS devices?

Yes. The repository lists physical-device lifecycle support through xcrun devicectl, including list, pair, install, launch, terminate, screenshot, and log capture workflows. It also documents extra iOS 17+ considerations for screenshots and logs.

How should I test adoption in a real team?

Start with one simulator profile, one app target, and one focused test target. Validate doctor, discovery, build, run, test, deep link, logs, and screenshot capture before expanding to device workflows.

Takeaways

Five keys:

1. XcodeBazelMCP turns Bazel Apple workflows into MCP tools and CLI commands.
2. It is designed for real development loops: discover, build, run, test, debug, capture, and inspect.
3. Workspace configuration is the foundation. Bad defaults create bad automation.
4. Simulator and device workflows have different failure modes, especially on newer iOS versions.
5. The tool works best when your team treats it as shared workflow infrastructure.

If you only remember one thing: Do not ask AI to guess your Bazel workflow; expose the workflow as explicit tools with clear workspace and target defaults.

[embed]GitHub - XcodeBazelMCP/XcodeBuildMCP: MCP server and CLI for Bazel-based Apple platform development… MCP server and CLI for Bazel-based Apple platform development - tools for iOS, macOS, tvOS, watchOS, visionOS builds…github.com