Macbox

What macbox does

The macbox MCP server lets an agent work with native Apple app projects from a machine that does not have macOS or Xcode installed locally. It provides a remote Mac mini and an iOS Simulator for common development checks: compiling an app, running tests, launching a build, viewing the screen, and interacting with the interface.

The service returns build output and error lines, including one PASS or FAIL result for each test. After an app is running, an agent can inspect the visible UI, tap controls, enter text, swipe, press buttons, and stop the process. A browser link is available for watching and manually using a running app.

How it works

macbox transfers the files tracked by Git to a dedicated macOS virtual machine. Environment files are excluded by default and are only sent when explicitly requested. After the initial transfer, only changed files are uploaded, while the build cache remains available for later builds.

The remote machine is a Mac mini running Xcode. The macOS VM is assigned to one user and is separated from other VMs and the provider’s network. MCP tools communicate with the macbox service, while the underlying command-line interface is also available for direct use.

For additional Xcode work, macbox mcp --xcode exposes the open-source MobileBuildMCP Xcode tools on the remote Mac. The provided material identifies capabilities such as LLDB debugging, Swift package operations, and simulator settings for this optional mode.

Setup and configuration

The macbox MCP server can be registered in an MCP client with Node 18 or newer:

{
  "mcpServers": {
    "macbox": { "command": "npx", "args": ["-y", "macbox", "mcp"] }
  }
}

Authentication uses macbox login, or the MACBOX_API_KEY environment variable. The API key is suitable for storing as a secret in a cloud agent. The repository also provides a macOS and Linux CLI installer; after installation, macbox setup installs the skill for Claude Code and Codex and adds usage notes to CLAUDE.md and AGENTS.md.

The macbox MCP server can also be installed through the Claude Code plugin, or the skill can be added with npx skills add opslane/macbox-agent for supported agent workflows. Access and free credit are provided through macbox.build; usage is charged by whole Mac minutes, with jobs shorter than one minute free.

Tools and capabilities

Available MCP tools include:

• build to build for the iOS Simulator or macOS for a Mac app
• test to run tests on a fresh simulator
• screenshot to launch the latest build and return an image
• run to launch the app and provide a live link
• describe, tap, type, swipe, press_button, and look for simulator UI interaction
• stop to end the running app
• report_problem to send service feedback

These tools correspond to commands in the macbox CLI, including macbox build, macbox test, and macbox ui operations.

Limitations and notes

The macbox MCP server is intended for native Apple projects. Supported project types include Xcode projects and workspaces, Swift packages, CocoaPods, and XcodeGen. Signing and TestFlight workflows are not currently supported. The README also lists React Native and Flutter as unsupported.

The service runs the project on a remote Mac rather than providing a local Xcode installation. A valid login or API key is needed, and Mac usage is metered. The open repository contains the client-side plugin, skill, npm package, and registry entry; the macbox service itself runs on the provider’s Macs. The repository is MIT licensed.