Device broker MCP server

Give several AI agents fair turns on your own Android emulators, iOS simulators, Mac and Windows desktops, Batocera retro-gaming boxes, and build slots. An agent gets a lease with the address its tools use (adb, simctl, ssh), a place in a fair queue, or the reason nothing can serve it (a Mac asleep, a host short of memory). The broker starts an emulator when its host has room and stops or resets every device after its lease, but drives none. Its write tools change who holds a device; nothing moves money, and nothing asks for a confirmation.

You need your own device hosts (Linux machines with the Android emulator, Macs with Xcode), reachable over ssh from the broker without a prompt; a catalog file naming them and their devices; and, for emulators the broker starts, a small control command on each Android host. There is no account and no key.

#What you can ask

• "Get me an Android emulator for the next hour to test the sign-up flow."
• "Which devices are free right now, and who holds the iPhone simulators?"
• "Lease an iPhone simulator a Maestro flow can drive, and wait in line if they're all taken."
• "Hold my emulator while Ana signs in to the test account, then take it back."
• "I'm done with the emulator. Reset it and give it back."
• "The simulator won't boot: quarantine it so nobody else gets it."

#Install

With Claude Code:

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add devices -e DEVICES_CATALOG_FILE="<path to Device catalog>" -- node "$PWD/servers/devices/dist/index.js"

Claude Desktop (Settings, Developer, Edit Config) and most other clients read the same command as JSON, with the full path of servers/devices/dist/index.js in your clone:

{
  "mcpServers": {
    "devices": {
      "command": "node",
      "args": ["<path to the clone>/servers/devices/dist/index.js"],
      "env": {
        "DEVICES_CATALOG_FILE": "<path to Device catalog>"
      }
    }
  }
}

Configuration says what it holds. To share one running copy between several clients over HTTP, see docs/deploying.md.

Agents that share devices must share one broker, over HTTP (MCP_HTTP_PORT, docs/configuration.md), each client with its own token (Tenants): the leases live in that one process, and two brokers would each lease a device the other holds.

#Configuration

#Reaching the hosts

The broker reaches each host over ssh as its own user, with BatchMode=yes, so that user's ssh configuration (a key in ~/.ssh/config, an agent, or an identity-based SSH such as Tailscale SSH) must let it in without a prompt. Host keys are accepted on first contact and pinned in the state directory.

• An Android host is Linux with the Android emulator, and a control command for the emulators the broker starts. The broker reads its memory and load (/proc/meminfo, /proc/loadavg). An emulator without a probe is read through an adb server on the broker's own loopback at its adb.port: run the broker on the host, or forward the host's adb server (ssh -N -L 5037:127.0.0.1:5037 builder@android-host.example.com).
• An iOS host is a Mac with Xcode (xcrun simctl). The broker reads its power (pmset), load (sysctl vm.loadavg) and simulators, and whether a CI job runs or a desktop session is open (How it works).

#The catalog

One JSON file, read at start. Every name, address and number below is invented.

{
  "box": "broker-1",
  "session_hint": "the output of `show-session-id` (Claude Code's $CLAUDE_CODE_SESSION_ID)",
  "wrappers": { "android": ["apk-run", "flow-run"], "ios": ["sim-run"] },
  "profiles": {
    "android-phone": "Android 14 (API 34) emulator, 1080x2400 at 420 dpi",
    "android-phone-15": "Android 15 (API 35) emulator, 1080x2400 at 420 dpi",
    "ios-phone": "iPhone 16 on the newest installed iOS runtime",
    "ios-watch": "iPhone 16 with an Apple Watch paired, newest iOS and watchOS runtimes",
    "batocera": "Batocera on a VM, a fresh box from the stock image for every lease"
  },
  "default_profiles": { "ios": "ios-phone" },
  "hosts": [
    { "id": "android-host", "label": "the Linux box", "platform": "android", "ssh": "builder@android-host.example.com",
      "spawn_max": 2, "cost_mib": 8192, "reserve_mib": 8192, "builders": 1, "control": "/usr/local/bin/emulator-ctl" },
    { "id": "mac-1", "label": "the Mac mini", "platform": "ios", "ssh": "runner@mac-1.example.com",
      "requires_ac": false, "spawn_max": 1, "builders": 1 }
  ],
  "devices": [
    { "id": "emulator-5554", "platform": "android", "host": "android-host", "profile": "android-phone",
      "mode": "spawn", "maestro": true, "instance": "phone1", "adb": { "port": 5037, "serial": "emulator-5554" },
      "variants": [{ "profile": "android-phone-15", "instance": "phone1api35" }] },
    { "id": "emulator-5556", "platform": "android", "host": "android-host", "profile": "android-phone",
      "mode": "spawn", "maestro": true, "instance": "phone2", "adb": { "port": 5037, "serial": "emulator-5556" } },
    { "id": "batocera-1", "platform": "batocera", "host": "android-host", "profile": "batocera", "mode": "spawn",
      "instance": "bato1", "probe": "unit", "cost_mib": 4096,
      "ssh": { "target": "root@127.0.0.1", "port": 2223, "jump": "builder@android-host.example.com" },
      "screenshot": "ffmpeg -loglevel error -f x11grab -i :0 -frames:v 1 -f image2pipe -c:v png -" },
    { "id": "dev-iphone", "platform": "ios", "host": "mac-1", "profile": "ios-phone", "mode": "fixed", "maestro": true,
      "simulator": { "name": "dev-iphone", "type": "iPhone 16" } },
    { "id": "spare-iphone-1", "platform": "ios", "host": "mac-1", "profile": "ios-phone", "mode": "spawn", "maestro": true,
      "simulator": { "name": "spare-iphone-1", "type": "iPhone 16" },
      "note": "created on first use, shut down after each lease" },
    { "id": "spare-watch-1", "platform": "ios", "host": "mac-1", "profile": "ios-watch", "mode": "spawn", "maestro": true,
      "simulator": { "name": "spare-watch-1", "type": "iPhone 16",
                     "watch": { "name": "spare-watch-1-watch", "type": "Apple Watch Series 10 (46mm)" } },
      "note": "leased only by its profile; the watch is created, paired and shut down with the phone" },
    { "id": "ci-iphone", "platform": "ios", "host": "mac-1", "profile": "ios-phone", "mode": "reserved",
      "simulator": { "name": "ci-iphone", "type": "iPhone 16" }, "note": "CI's own; shown, never leased" }
  ]
}

Top level:

A host:

A device:

A macos device is a Mac's desktop session: fixed, on an ios host. A windows VM or a batocera box the broker starts is a spawn slot with an instance and probe "unit", on an android host, the only kind whose probe reads the control command. The catalog is checked at start against every rule above; if it breaks one, every tool says which.

#The control command

The broker starts and stops emulators and VMs only through the host's control command, over ssh, so its ssh account needs no other privilege: the command may hand the request to a privileged service that starts nothing but its own emulators. It must answer three calls:

A batocera instance is a fresh box on every start: start boots it from the stock image on a new disk (an overlay over the image, say) and stop throws that disk away. The broker stops a box after every lease, so that stop is its reset, and the next holder never sees what the last one did.

A slot's variants are instances like any other; status lists a slot's profiles and the one it runs. Only one runs at a time (they share the slot's serial and ports), so the broker stops any other it saw running before starting one. A non-zero exit is a failure, and the last lines of stderr are the reason the broker gives. With one systemd unit per emulator, for example:

#!/bin/sh
# /usr/local/bin/emulator-ctl: this host's emulators, one unit each (emulator@phone1, ...).
case "$1" in
  start)  systemctl --user reset-failed "emulator@$2" 2>/dev/null
          exec systemctl --user start --no-block "emulator@$2" ;;
  stop)   exec systemctl --user stop "emulator@$2" ;;
  status) for i in phone1 phone1api35 phone2; do
            s=$(systemctl --user is-active "emulator@$i")
            if [ "$s" = failed ]; then echo "$i $s $(systemctl --user show -P Result "emulator@$i")"; else echo "$i $s"; fi
          done ;;
  *)      echo "usage: $0 start|stop <instance> | status" >&2; exit 2 ;;
esac

#Tenants

Over HTTP, each client has its own bearer token (token-<label> in MCP_HTTP_TOKENS_DIR, docs/configuration.md). A token labelled guest-<id> (<id> matching ^[a-z][a-z0-9]{1,15}$) is the tenant guest:<id>; every other label, and a stdio run, is default. A label that starts with guest and is not well formed owns nothing. A caller sees and acts on only its own tenant's devices: another tenant's device, lease or ticket answers as one that does not exist, and no reason, status line or event names it. Build slots run as the host's own ssh account, so they belong to the default tenant. A host's memory is one budget for every tenant.

#First run

1. Ask for the broker's status: each host's health, and why one is degraded or down. A catalog that did not load says why here.
2. Lease a device, drive it, and release it. From a shell, scripts/smoke.ts does the same against a running broker (MCP_URL, MCP_TOKEN_FILE), on each platform that is up.

#Tools

read changes nothing; write changes who holds a device, and may start, stop or reset one.

Some tool descriptions are written from the catalog (its wrappers, session_hint and profiles); none names a host.

#Sessions

Every tool that touches a lease takes session: 1 to 200 characters naming one agent session, the same on every call (Claude Code's $CLAUDE_CODE_SESSION_ID is one). It is not MCP's Mcp-Session-Id, which names one connection: a wrapper the agent runs opens its own, calls acquire (or renew) with the agent's id, and exports the lease's address.env.

• A lease belongs to the tenant and the session together. A session holds at most one device per platform and form (the catalog's forms), and asking again returns that lease and extends it. Asking with a profile that lease does not run is an input failure naming the device and the profile it runs: release it, then ask.
• renew, pause, resume and release find a lease by its lease id (ls-<n>), else by want, else they take the session's first lease.
• The session id is the client's claim, not a credential. Within one tenant, a caller that sends another session's id acts as that session; the boundary between tenants is the token.

#What a lease gives its holder

A granted device lease carries address, whose env its holder exports:

#Troubleshooting

acquire answers unavailable. Not a failure: the reason names every cause, such as a host down (asleep, off, locked after a reboot), a Mac on battery or busy, too little free memory, a device quarantined or not answering, or nothing in the catalog for what was asked. Fix the cause, or ask for something else.

acquire answers queued. Everything that could serve you is leased, resetting, or at its host's spawn_max: keep calling wait with the ticket.

acquire answers failed. The device the broker started for your lease did not boot: its host's control command reported its unit failed, and reason says why in the unit's words (batocera-1 did not start: its unit (bato1) failed (timeout)). The lease has ended and the device is being stopped; acquire again to get a fresh one. It is said once, to your session's next acquire for that platform within 10 minutes. A device that fails every time needs a look on its host: status's events record each failure.

A device stays booting. Ask again (acquire returns the same lease with its state), or pass until_booted to wait for the boot in one call.

A device shows not answering in status. A fixed simulator must exist exactly once by its name on its Mac. A Mac desktop needs someone logged in to that account; its why says so.

config. The catalog cannot be read or does not validate, or the state directory is not writable; the message names the rule. Fix it and restart the broker.

input. The call names something that does not exist or is not yours (a lease that ended, a dropped ticket, another session's lease), or a profile your lease does not run. status with your session lists what you hold.

host. A host refused or failed a command the broker sent (ssh, simctl, adb, the control command). status shows its health; a second try after a minute usually tells a blip from a fault. A stop that failed after a lease is retried within a minute; a failed reset shows in status's events, to check by hand.

#How it works

• A lease ends by itself after 20 minutes without a call from its holder (acquire or renew; a wait counts once granted), or when its time runs out, and is then treated as dirty. A queued grant never claimed goes back clean.
• A pause is a promise. The broker drives nothing, so the holder keeps it: a paused lease's view says do not drive it until resume. The 8-hour cap frees a forgotten pause.
• The queue is fair and forgets the dead: interactive before background, then by arrival. A ticket not polled for 2 minutes is dropped; a grant not claimed within 5 minutes passes to the next in line.
• Placement (domain/place.ts, pure): a free fixed device, else a spawn slot on a host with room, else the queue if something will come back, else unavailable with every reason. Room means up, under spawn_max, and on an Android host reserve_mib left after cost_mib for each emulator started since the last probe, so sessions asking within one minute do not all pass on one reading.
• A Mac is up on AC power, with no CI job running (a GitHub Actions Runner.Worker process) and a one-minute load of at most 12, since a simulator booting beside a CI job can starve the job. Otherwise it is degraded: it serves its fixed simulators and starts nothing.
• A lease is booting from its grant, which starts the slot, until the probe says it has booted (adb lists it as a device with sys.boot_completed set, or its unit is active).
• A start that fails ends its lease at once. When a probe begun after the broker started the slot finds the lease's instance failed (systemd gave up on it: a start timeout, an out-of-memory kill, the process exiting), the lease ends and the slot is stopped as after any lease, which clears the failed unit. An earlier probe does not count: it can still show the last run's failure. The slot is not quarantined, since a failed start may be transient, and the event log keeps it. The holder's wrapper is still asking acquire while it waits for the boot, so the session's next acquire for that platform and form, within 10 minutes, answers failed with the unit's reason, once, rather than quietly handing it another device; status and wait leave that answer for it.
• After a lease, an emulator or VM the broker started is always stopped; after a dirty one, every third-party app's data is cleared first (pm clear). A simulator is always shut down, since a booted one costs its Mac gigabytes; dirty also uninstalls the holder's apps and resets privacy grants. A fixed emulator stays running, its apps' data cleared after a dirty or broken lease. The device stays busy until this is done, so the queue never hands it on mid-stop.
• Nothing runs without a lease. Each tick stops an emulator slot the last probe saw running with no lease and no work in progress (once per probe), so a host returns to zero emulators whatever started one: a failed stop, a broker restart, a hand.
• Desktops and Batocera boxes. A macos device is present while the host's ssh account has a desktop session (launchctl print gui/<uid>), which the broker never starts or ends. A windows VM or a batocera box is started and stopped like an emulator, but with no adb, dirty clears nothing on it; a Batocera box needs nothing cleared, since its stop throws it away (the control command).
• Simulators are found by name, and handed out only when exactly one of that name exists on the Mac: with two, a holder may drive the wrong one. A spare is created on the newest installed iOS runtime when first granted, and deleted after 7 days unused.
• Paired watches. Each grant of a spare with a watch creates whichever of the phone and the watch is missing (the watch on the newest installed watchOS runtime) and pairs them unless simctl list pairs shows the pair, mending one undone by hand; a watch paired with another phone is refused, not taken. The holder boots the watch like the phone (simctl boot $IOS_SIM_WATCH). After every lease, each watch paired with the phone is shut down (its apps uninstalled after dirty); it is deleted with the phone.
• adb without the adb binary. The binary starts a server when none answers on its port, squatting a port meant for a forward. So the broker speaks adb's host protocol over a socket (infra/adb.ts), and to a door, adb's device protocol straight to the slot's adbd (infra/door.ts). A door's device must not ask for adb authentication (ro.adb.secure=0), so the tunnel's own (mutual TLS, say) is the boundary.
• State is one JSON file, written whole after each change, one change at a time, so concurrent calls cannot lose an update and leases survive a restart (work a restart cut short is forgotten). The clock ticks every 15 seconds; hosts are probed at most once a minute.

#Limitations

• One broker per set of devices: its state is one process and one file.
• Emulators and simulators only, no physical phones. Android hosts are Linux and iOS hosts are Macs. A simulator shares its Mac's network and identity, so a Mac serves the default tenant only, unless its catalog entry says it isolates its devices, which the check takes at its word.
• An adb server is reached on the broker's loopback only, never across a network: an adb server listening beyond loopback hands its devices to anyone.
• The catalog is read at start; a change needs a restart.
• A build slot is only a slot: the broker counts it, the holder builds.
• Session ids are not authenticated within a tenant (Sessions).

#Other servers for mobile devices

Searched 2026-10-15. Most mobile servers drive a device rather than hand one out:

• Drivers use whatever device is running: @mobilenext/mobile-mcp, Appium's appium-mcp, Maestro's built-in maestro mcp.
• Device clouds lease their own phones, not yours: BrowserStack (@browserstack/mcp-server, also hosted), Sauce Labs (a hosted server and sauce-api-mcp), Firebase (a run_test tool in firebase-tools), and hosted disposable devices from Limrun and AgentCloud. AWS publishes none for Device Farm.

Three do share devices among agents:

• Callstack's agent-device (CLI, MCP and Node API) also drives the device. It keeps parallel agents on one machine off each other's simulators and emulators, and has a proxy with a bearer token, tenants and leases that expire when idle; a busy device is an error, not a queue.
• manzanas brokers iOS simulators on several Macs with TTL leases, FIFO queues, a warm pool and a reset after each lease, over stdio with no authentication.
• berth leases Android emulators on Kubernetes, one Pod per lease, over HTTP with a single token.

None of them does all of this in one place: Android emulators on Linux, iOS simulators on Macs and build slots in one queue; a device started only on a healthy host with room, and the reason said when nothing can serve; every device stopped or cleaned after its lease, a wedged one quarantined; each client's token deciding which devices it sees. This one drives nothing: a lease gives the address a driver such as Maestro uses. For iOS simulators alone, manzanas is faster to a ready device, with its warm pool, and also drives it.