SAIR MCP server
Commit Nov 5, 2026Lets an AI client run Android instrumented tests, lease physical devices, install APKs, run shell commands, and capture screenshots or logcat.
Also known as compscidr/sair
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.36
- Last commit
- Nov 5, 2026
- License
- Apache-2.0
What is SAIR MCP?
SAIR lets an AI client run Android instrumented tests, lease physical devices, install APKs, run shell commands, and capture screenshots or logcat.
Summary generated from the project's README
About SAIR MCP server
SAIR provides a way for AI agents and CI pipelines to safely share and manage physical Android devices. It acts as an orchestrator that prevents multiple jobs from colliding on the same hardware by using a device locking system and a proxy. This ensures that one job cannot interfere with another by installing conflicting APKs or changing system settings mid-run.
Developers can use the sair-mcp server via stdio to give coding agents direct control over mobile hardware. By providing a SAIR_API_KEY from sair.run, an agent can lease a device, install specific APKs, execute shell commands, capture screenshots, and read logcat output. The server handles the complexities of device isolation, including automatic uninstallation of test packages and resetting network settings upon release. This setup allows for automated instrumented testing on real hardware without requiring the agent's local machine to have ADB or a direct connection to the phones.
What you can do with it
- 1Run automated instrumented testsAn AI agent can upload an application and its test APK to a real phone and retrieve the results along with logcat output.
- 2Debug mobile applicationsA developer can instruct an agent to capture the current screen state or pull recent system logs to diagnose an issue.
- 3Manage device hardware stateAn agent can check which physical phones are available and their specific hardware specifications before starting a task.
- 4Execute remote shell commandsAn AI client can perform specific system-level operations on a leased Android device using shell commands.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
SAIR_API_KEYRequiredSecretAn API key from https://sair.run/dashboard
ACQUIRE_OUTPUTSAIR_API_URLAgent API base URL (default: https://api.sair.run)
SAIR_GUEST_API_KEYS
| Name | Description | |
|---|---|---|
| SAIR_API_KEY | An API key from https://sair.run/dashboard | RequiredSecret |
| ACQUIRE_OUTPUT | — | |
| SAIR_API_URL | Agent API base URL (default: https://api.sair.run) | |
| SAIR_GUEST_API_KEYS | — |
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecompscidr/sair is public and reachablegithub.com/compscidr/sair ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-05github.com/compscidr/sair ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSAIR — Shared Android Instrumented Runner
SAIR lets CI pipelines safely share physical Android devices. It provides device locking, ADB protocol translation, and per-runner isolation so multiple jobs never collide on the same device.
Why
Without SAIR, every CI job that can see a phone uses it at the same time:
CI job 1 ──┐
├──▶ adb ──▶ Phone ✗ both jobs install / uninstall the same APK
CI job 2 ──┘ ✗ one job's reboot or settings change breaks
the other's tests mid-run
✗ connectedCheck runs on every attached
phone, including ones another job is using
With SAIR, a job must hold a lock before it sees a device, and waiting jobs queue:
CI job 1 ──┐ ┌──▶ Phone A (locked by job 1)
├──▶ Proxy ───────┤
CI job 2 ──┘ ▲ └──▶ Phone B (locked by job 2)
│ locks
CI job 3 ··· Orchestrator: job 3 waits in the queue until
a phone is released
GitHub Action
This repo is also a GitHub Action that puts sair-acquire, sair-release,
sair-wifi, sair-bluetooth, sair-locks and sair-label on PATH. The tools need an orchestrator account: sign up at
sair.run to get an API key, store it as the repository
secret SAIR_API_KEY, and set the repository variable SAIR_PROXY_URL to
your bench's proxy (see Run). Then:
steps:
- uses: actions/checkout@v4
- uses: compscidr/sair@v0.1.18
- run: sair-acquire --count 1 > /dev/null
env:
SAIR_PROXY_URL: ${{ vars.SAIR_PROXY_URL }}
SAIR_API_KEY: ${{ secrets.SAIR_API_KEY }}
- run: ./gradlew connectedCheck
- if: always()
run: sair-release --status ${{ job.status }}
env:
SAIR_API_KEY: ${{ secrets.SAIR_API_KEY }}
The full workflow example explains each step.
A runner with no proxy of its own (e.g. GitHub-hosted, using phones other
accounts share) can have the action start one, at the same release as the
action. Leave SAIR_PROXY_URL unset; the proxy listens on the default
localhost:8550, and its log is at $RUNNER_TEMP/sair-proxy.log:
- uses: compscidr/sair@v0.1.18
with:
proxy: true
env:
SAIR_API_KEY: ${{ secrets.SAIR_API_KEY }}
Used at a branch or SHA rather than a release tag, the action warns and starts the latest release instead.
AI agents (MCP)
sair-mcp is an MCP server (stdio) for coding agents. It can run an app's
instrumented tests on a real phone in one call, or lease a phone and install
APKs, run shell commands, take screenshots and read logcat on it. It talks to
the orchestrator's agent API with an API key from sair.run.
The agent's machine needs no proxy or adb.
Install it with go install github.com/compscidr/sair/cmd/sair-mcp@latest,
take sair-mcp from a release tarball, or use sair-mcp.mcpb from a release
(an MCP Bundle for clients
such as Claude Desktop). Then add it to your agent, e.g. Claude Code:
claude mcp add sair -e SAIR_API_KEY=sair_... -- sair-mcp
or any client's JSON config:
{ "mcpServers": { "sair": { "command": "sair-mcp", "env": { "SAIR_API_KEY": "sair_..." } } } }
| Tool | Does |
|---|---|
run_tests |
Uploads app_apk and test_apk (paths on the agent's machine), waits for the run, returns per-test results, instrument output and a logcat tail |
list_devices |
Lists the phones the key may use: serial, model, sdk (API level), shared, in use |
lease_device |
Takes a phone (serial, wait_s optional) and returns the lease id |
install_apk |
Installs an APK on the leased phone, returns its package |
shell |
Runs a command, returns output and exit code |
screenshot |
Returns a PNG of the screen |
logcat |
Returns the most recent lines (default 500) |
release_device |
Ends the lease: uninstalls what it installed and frees the phone |
The server heartbeats the leases it takes, so an agent that thinks for a while
between calls keeps its phone. A lease still ends at the plan's maximum
(free 15 min, solo 1 h, team 2 h, enterprise 4 h). On a phone shared by another
user, shell commands are limited to a safe set (see the orchestrator README).
SAIR_API_URL points it at another orchestrator (default
https://api.sair.run).
It is listed in the official MCP registry
as io.github.compscidr/sair. Every release publishes it: the release
workflow builds sair-mcp.mcpb, fills server.json's version, download URL
and SHA-256 (the values in the repo are placeholders), and publishes it with
mcp-publisher, logged in through GitHub OIDC. Check it with
curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.compscidr/sair".
Quick Start
Install
curl -fsSL https://raw.githubusercontent.com/compscidr/sair/main/install.sh | bash
This detects your OS and architecture, downloads the latest release, and
installs all binaries to ~/.local/bin.
Prerequisites
adbinstalled on the machine with Android devices- One or more Android devices connected via USB with USB debugging enabled (don't sign them in to a personal account: see Securing a bench)
Run
# 1. Start a real ADB server on a non-default port (5038), so it doesn't
# conflict with the proxy which will own the standard port (5037).
adb -P 5038 start-server
# 2. Set your API key (shared by proxy and device-source)
export SAIR_API_KEY=your-api-key
# 3. Start the proxy and device source
sair-proxy &
sair-device-source
The proxy connects to the hosted orchestrator at orchestrator.sair.run by
default (with TLS). Override with ORCHESTRATOR_ADDR for local development.
Use
Acquire a device lock (blocks until one is available), run your tests, then release:
ACQUIRE_OUTPUT=$(sair-acquire)
eval "$ACQUIRE_OUTPUT"
./gradlew connectedCheck
sair-release
After eval, stock adb automatically talks to the proxy through the scoped
port and only sees the locked devices.
When the bench sets WIFI_SSID on the device source, Wi-Fi is managed for
you:
- On acquire each phone joins the bench Wi-Fi and the acquire returns only
once the phone is online (below); it fails otherwise.
--no-wifihands it over offline instead, verified the same way rather than trusting the previous release.--wifi-band 2.4|5|6(alsosair-wifi on --band) joins on that GHz band: the phone scans, the suggestion is pinned to the strongest BSSID ofWIFI_SSIDit sees in the band, and the join fails if it sees none. The phone'scmd wifi statusshows the BSSID and frequency it joined. - On release, and when a lock expires or is cancelled, each phone is reset:
every suggestion added through
adb shelland every saved network is forgotten and the radio is toggled, and the reset waits until the phone is offline with the radio back on. The next job never inherits the last one's network. The phone then rejoins the bench Wi-Fi, so it is online between leases and app updates can install (see the Play Store below); the next acquire puts it in the state that job asked for either way. - Also on release, every third-party package the phone did not have when
the device source first saw it is uninstalled (test APKs and
.testpackages included, with their app data and signed-in accounts), and the browser and mail apps are force-stopped; seeBASELINE_PACKAGES,RESET_FORCE_STOPandRESET_CLEAR_PACKAGES. What was removed is written to the proxy log and the lock's log on the orchestrator, naming any Wi-Fi suggestion that went with a package. This runs before the Wi-Fi reset, so a suggestion a test app leaked for the bench network is gone before the reset waits for the phone to be offline. - A phone relayed to a borrower resets differently: the first relay under a
lock lists its third-party packages, and when the lock ends only what is not
on that list is uninstalled, for the primary user only. An app on the phone
before a lock's first relay stays; one installed during the lock goes, whoever
installed it.
BASELINE_PACKAGEShas no effect on this reset, but a local or guest-key lock on the same phone still resets to the baseline, so list apps to keep inBASELINE_PACKAGES. What was removed goes to the proxy log and the bench events, not the lock's log, which is on the holder's proxy. Without that list (it could not be read, the device source is older than the proxy, or no relay got that far) nothing is uninstalled: the proxy logs a warning and reports a failed package reset. Leftovers can then survive until a local lock, because the next borrower's list includes them, as it does when a relay under a new lock arrives before the previous lock's reset (the proxy warns, naming what it suspects). - On acquire the same cleanup runs first (reverse forwards, packages),
before the Wi-Fi check. A job that never released, because it had no
if: always()release step, its runner died, or the proxy was down when the lock expired, is cleaned up by the next job, whose lock log then showssair: uninstalled … (left by an earlier job). This is local locks only: a relayed lock's next job cleans up nothing. - No leaked UiAutomation, on release and on acquire: a killed
am instrumentor a leftover uiautomator server can leave a UiAutomation registered, failing every later instrumentation withUiAutomationService … already registered!. Auiautomator dumpprobe detects it; sair then kills the shell user'sapp_process/uiautomatorprocesses, which unregisters it, and reboots only if the probe still fails (never a phone with a secure lock). The lock log getssair: cleared a leaked UiAutomation registration (killed … | rebooted). - Awake and unlocked, on acquire and again after the release reset: the
screen is woken and the keyguard dismissed, then verified (
dumpsys powersaysAwake,dumpsys window policysays the keyguard is not showing), with up to three attempts since a one-shot dismiss can race on some phones. A phone whose keyguard stays up fails the acquire withscreen locked; that means a PIN, pattern or password is set, which sair cannot dismiss, so set the phone's screen lock to Swipe or None. The reason is also reported as the device'swarning(proxy/status, device report) until a wake succeeds. A phone withstay_on_while_plugged_inoff is logged as a warning, since it will sleep and re-lock between steps. Android 4.x phones (nowm) are verified through their ownmShowingLockscreenfield; a dump in a format sair does not know is logged once and treated as unlocked. - Rebooted on release once its uptime is over
REBOOT_UPTIME_HOURS(24 by default), while the phone is unacquired: the reset waits for the boot and the wake above before the next acquire of that phone can proceed, and the phone is not offered while it is down. The lock log getssair: rebooted after release (uptime …)and the proxy's/statuslists each phone'slast_reboot. This runs before the Wi-Fi reset, so the offline wait is not spent twice. A phone with a PIN, pattern or password is never rebooted this way, since it would come back on "unlock to start" and need a human; the device source logs that with the fix. The wake and the reboot run whether or not the bench manages Wi-Fi. - Bluetooth cycled on release, after the Wi-Fi reset:
svc bluetooth disable, wait untildumpsys bluetooth_managersays the adapter is fullyOFF,svc bluetooth enable, wait until it saysON(30 s each). A BLE stack an earlier job wedged (stuck advertisers, a scanner that never restarted) does not reach the next job as "No peers discovered". Disable alone often stops atBLE_ON(classic off, BLE still up for "Nearby device scanning" or an app that asked for BLE), so sair turnsble_scan_always_enabledoff for the cycle and, if BLE is still held, force-stops the packages the dump lists as BLE apps (on One UI,com.samsung.android.beaconmanagerandcom.samsung.android.mdx.kit). A holder that survives that too (the Galaxy A06's Auto Hotspot scanner lives insystem_server, listed asandroid) is cleared by airplane mode, scoped to Bluetooth throughairplane_mode_radiosso Wi-Fi and cell stay connected. The settings are restored before Bluetooth comes back on. Skipped after an uptime reboot, and done on acquire instead when no release reset ran since the phone's last job (or since the proxy started). The lock log getssair: Bluetooth cycled off and on (…). A radio that does not go fully off or come back on is in the lock log and is the device'swarninguntil a cycle succeeds, but does not fail the acquire, since most jobs never use Bluetooth. Bluetooth is always left on: a radio that never goes fully off is still turned back on, and the line says so (Bluetooth back on but never fully off: ... adapter is BLE_ON). Phones without the adapter dump (Android 4.x) are skipped. - Mid-job,
sair-bluetooth restartruns the same cycle on the job's own phones and returns once the adapter isON, for a suite that tests recovery from a Bluetooth stack restart (sair#156). A test that force-stopscom.android.bluetoothitself instead races the cycle sair ran a minute earlier and gets stale adapter state. The lock log getssair: Bluetooth cycled off and on (…) (requested by the job); a failure is returned to the caller and the lock is kept. From the phone, a test calls it with the lock's device token like Wi-Fi; see Device-side control. - No Play Store updates during a lease: on acquire the Play Store is
disabled (
pm disable-user com.android.vending) and on release it is enabled again, so updates install between leases, when the phone is back on the bench Wi-Fi (or mobile data). An update of Google Play services force-stops every app that uses it, the app under instrumentation included, which fails a job withProcess crashed. The lock log getssair: Play Store disabled for the lease. A phone that refuses (Xiaomi:Cannot disable system packages) says so in the lock log and keeps the lock. Phones without the Play Store and Android 4.x (whosepmcrashes on it) are skipped. A job that needs the Play Store itself (billing, in-app updates, Play Integrity) cannot use it on these phones. - Rebooted when a radio is wedged: each
svc wifi/svc bluetoothtoggle and radio state read is bounded (15 s). When the Wi-Fi reset or the Bluetooth cycle fails, the device source probes the radio's service (dumpsys wifi/dumpsys bluetooth_manager); only if that hangs too is the phone rebooted (same rules as the uptime reboot) and the reset run again. A phone that hangs onsvcwith a healthy radio is not rebooted. The lock log getssair: radio wedged (wifi|bluetooth), rebooted, and a radio still bad after the reboot fails the reset as before.
A bench that was already running jobs has phones carrying the last job's
packages, so "first seen" would record those into the baseline. A test package
and its target, where pm list instrumentation names both and both are
installed, are never baselined, which covers CI leftovers without touching
apps that merely ship an instrumentation of their own; for anything else, or to
be certain, set
BASELINE_PACKAGES explicitly after one look at pm list packages -3 on each
phone (set it empty to keep no third-party package at all). The device source
logs the baseline it recorded, by name, so an unwanted entry is visible in the
first log after the upgrade.
- Mid-job,
sair-wifi off/sair-wifi ondrop and restore the network without the job knowing the credentials, and return only once the phone is offline or online. Each phone is switched on its own, so two phones can ask for opposite states at the same time. - From the phone, a test can toggle its own Wi-Fi between two assertions with the lock's device token; see Device-side control.
Online means all of: associated to WIFI_SSID itself (not a SIM or a
leftover network answering instead), that Wi-Fi is Android's validated default
network (the same verdict the app under test gets), and WIFI_PING_HOST
answers, which with the default hostname proves DNS too. A VPN on top of that
Wi-Fi is fine. Offline means not on WIFI_SSID and WIFI_PING_HOST does
not answer; another network without an uplink, such as a test's own Wi-Fi
Direct group, still counts as offline. Each wait is bounded
(WIFI_CONNECT_TIMEOUT_SECONDS, WIFI_DISCONNECT_TIMEOUT_SECONDS) and a
timeout says which part failed, e.g. associated to "Cafe", not "bench",
connected but not VALIDATED, or still associated to "bench". Mobile data
is not managed: a phone with a SIM is never offline by this definition.
The device source counts each phone's Wi-Fi on attempts since it started:
failures by reason (not_associated, other_ssid, not_validated,
no_route, other), the last failure, and the latest, median and slowest
time to online. The proxy's /status lists them per phone as wifi, with a
hint when the slowest join comes near WIFI_CONNECT_TIMEOUT_SECONDS (raise
it) or most failures never associated (move the phone or the AP). A phone that
fails one join in ten, after at least five, is also logged as a warning.
A suggestion for the bench network registered by a test app's own uid is not
sair's to remove, but the app is: the package reset on release uninstalls it,
and Android drops its suggestions with it. Only a package in the baseline (a
test app that was on the phone when the device source first saw it) can keep
re-joining the bench Wi-Fi after every forget; --no-wifi acquires on that
phone then fail with still associated to "bench" until it is uninstalled or
left out of BASELINE_PACKAGES.
The Wi-Fi reset does not touch suggestions a test app registered under its own uid; those go when the package reset uninstalls the app. Devices relayed from another proxy are left alone.
The passphrase never goes on the adb command line: adbd logs every shell
service it serves to the phone's logcat, where the next job could read it, so
the device source feeds its commands to sh over stdin. A job that runs
cmd wifi add-suggestion itself through the scoped port has the command
redacted in the device source log and in the lock log.
When an acquire or a release reset fails on a phone, the lock log gets the
proxy's and the device source's recent log lines about that phone and lock
(sair: proxy log before the failure, and the same for the device source),
so the failure can be read from the portal without ssh to the bench. Lines
about the bench's other phones and locks are left out. The proxy also sends
the orchestrator small events on its session (acquire outcome and wait time,
Wi-Fi join time or failure cause, packages removed, reboots, versions, a
device source going stale) for the portal's per-phone view.
Architecture
┌──────────────────────────┐
│ DeviceSource │
│ + Phone │
│ + real adb (port 5038) │
└────────────▲─────────────┘
│ gRPC
▼
┌──────────────┐ ┌──────────────┐
│ Proxy │◄gRPC─▶│ Orchestrator │
│ (port 5037) │ └──────────────┘
└──────────────┘ (locks & sessions)
▲ ▲
ADB │ │ HTTP
(port 5037│ │(port 8550)
│ │
----------------+-------+---------------- CI runner --
▼ │
┌────────────┐ │ ┌─────────────────┐
│ adb client │ └───│ sair-acquire / │
│ (thinks it │ │ sair-release │
│ talks to │ └─────────────────┘
│ real adb) │
└────────────┘
DeviceSource runs on each machine that has Android devices connected via
USB. It discovers devices through a real adb server (running on a non-standard
port like 5038) and registers with the proxy over gRPC. You can run device
sources on as many machines as you like.
Proxy is the central hub. Device sources register with it, and it discovers
devices and routes commands through them. It talks to the orchestrator over gRPC
for lock and session management. It listens on port 5037 — the standard ADB
port — so stock adb on CI runners thinks it's talking to a real ADB server.
Orchestrator manages device locks, sessions, and coordination. The proxy
talks to it over gRPC. It does not connect to device sources or use ADB
directly. A hosted orchestrator is available at sair.run.
Tools (sair-acquire / sair-release) are thin bash wrappers that call
the proxy's HTTP API (port 8550) to acquire and release device locks.
ADB client — stock adb on the CI runner connects to the proxy on port
5037 (the standard ADB port). The proxy translates ADB protocol messages into
gRPC calls, so CI tools like ./gradlew connectedCheck work without any
modification.
Configuration
SAIR MCP questions
What can the SAIR MCP server do?
It can run an app's instrumented tests on a real phone, lease a phone, install APKs, run shell commands, take screenshots, and read logcat.
How do I install the SAIR MCP server?
You can install it using go install github.com/compscidr/sair/cmd/sair-mcp@latest, download a release tarball, or use an MCP Bundle.
Does the agent's machine need ADB installed?
No, the agent's machine does not require a proxy or ADB to use the server.
How long can I lease a device?
Lease durations depend on your plan: free is 15 minutes, solo is 1 hour, team is 2 hours, and enterprise is 4 hours.