# macbox [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/opslane/macbox-agent  
**GitHub Stars:** 0  
**npm Downloads (last month):** 40  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/macbox

## Description
A real Mac for your agent: build, test, run, and tap through iOS apps on the simulator.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "macbox": {
    "command": "npx",
    "args": ["-y","macbox"],
    "env": {
      "MACBOX_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `MACBOX_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/macbox/readme_