English Français العربية

macbox

Official registry AI and agents

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

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package macbox
Claude Code 
claude mcp add macbox -e 'MACBOX_API_KEY=<your macbox_api_key>' -- npx -y macbox@0.6.2 mcp
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "macbox": {
            "command": "npx",
            "args": [
                "-y",
                "macbox@0.6.2",
                "mcp"
            ],
            "env": {
                "MACBOX_API_KEY": "<your macbox_api_key>"
            }
        }
    }
}

Environment variables

  • MACBOX_API_KEY secret Your macbox API key (mbx_...). Optional if you ran `macbox login`.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. macbox
  2. Set up
  3. What your agent gets
  4. How it works
  5. This repository

macbox

A real Mac for your coding agent. macbox lets Claude Code, Codex, Cursor, or any MCP client build, test, run, and tap through native iOS apps on a real Mac in the cloud, from any machine, including Linux boxes and cloud agent sandboxes.

  • Build and test: xcodebuild and your XCTest and UI tests, on a Mac mini running the latest Xcode. Your agent gets the results and the error lines.
  • Run and drive the app: launch it on the iOS simulator, read what's on screen, tap, type, and swipe, so your agent can check its own work.
  • Watch live: every running app gets a browser link where you can watch and use it too.

Pay per Mac minute, whole minutes only: $0.05, and a job under a minute is free. Get access and free credit at macbox.build.

Set up

The quickest way: tell your agent

Set up macbox by following https://api.macbox.build/guide/

Or pick your client:

Claude Code (plugin: skill + MCP tools)

claude plugin marketplace add opslane/macbox-agent
claude plugin install macbox@macbox

Any MCP client (Codex, Cursor, Claude Desktop, VS Code, ...), with Node 18+:

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

The CLI (macOS or Linux):

curl -fsSL https://api.macbox.build/install.sh | sh
macbox login
macbox setup      # installs the skill for Claude Code and Codex, and notes in CLAUDE.md / AGENTS.md

Just the skill (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and more):

npx skills add opslane/macbox-agent

If the CLI isn't set up yet, the skill sends your agent to the guide to install it.

Log in with macbox login, or set MACBOX_API_KEY (in a cloud agent, as an environment secret).

What your agent gets

MCP toolCLIWhat it does
buildmacbox buildBuild for the iOS simulator (or macOS, for a Mac app)
testmacbox testRun tests on a fresh simulator; one PASS/FAIL line per test
screenshotmacbox screenshotLaunch the last build and return a picture
runmacbox runLaunch the app and keep it running; returns a live link
describe, tap, type, swipe, press_button, lookmacbox ui ...Use the running app like a person
stopmacbox stopEnd the running app
report_problemmacbox feedbackTell the macbox team when something on our side is wrong

For deeper work there is also macbox mcp --xcode: Sentry's open-source MobileBuildMCP Xcode tools (LLDB debugging, Swift packages, simulator settings), running on the macbox Mac.

How it works

macbox sends the files git tracks (never .env files unless you ask) to one Mac mini, into your own macOS VM that only you use and that can't reach other VMs or our network. Only changed files are sent after the first time, and the build cache stays, so the second build is fast. Native iOS apps work today: Xcode projects and workspaces, Swift packages, CocoaPods, XcodeGen. Not yet: signing, TestFlight, React Native, Flutter.

Full guide: https://api.macbox.build/guide/ · Questions: Discord

This repository

The open parts of macbox: the Claude Code plugin (.claude-plugin/, skills/, .mcp.json), the macbox npm package (npm/, which downloads the CLI from api.macbox.build and checks it against the published SHA256SUMS), and the MCP Registry entry (server.json). The macbox service itself runs on our Macs.

MIT licensed.

Frequently asked questions

What is macbox?

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

How do I install macbox?

It runs on your machine. In Claude Code: claude mcp add macbox -e 'MACBOX_API_KEY=<your macbox_api_key>' -- npx -y macbox@0.6.2 mcp. For other clients, paste the JSON configuration from this page into their MCP settings.

Does macbox need an API key?

Yes. It expects MACBOX_API_KEY, which you set in its configuration.

Is macbox open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains macbox?

It is published by opslane. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.