erius-phone-mcp

erius-phone-mcp

An MCP server that turns yourERIUS PHONE device into native tools for Claude Code,Claude Desktop, Cursor, or any other MCP client. An ERIUS PHONE device is a realAndroid phone or tablet dedicated to your agent. Once this server is connected,your agent can:

• list its devices
• read the screen as an accessibility tree or a screenshot
• tap, long-press, type, swipe and scroll
• launch and stop apps, open URLs and send intents
• install and uninstall APKs
• pull crash logs

The agent drives the device directly. You don't write any glue code.

Early access: this package is pre-1.0 (0.1.0). Tool names andarguments may still change before 1.0.

Requirements

• Python 3.10+
• An ERIUS PHONE API key. Sign up at https://eriusphone.com; see"Getting an API key" below.

Install

Option A: uvx (no install step). If you haveuv, your MCP client can launch the server withuvx erius-phone-mcp. uv fetches the package and keeps it in its ownenvironment. The client configs below show this form.

Option B: pip, into its own virtual environment so its dependenciesdon't clash with your other Python projects:

python3 -m venv ~/.venvs/erius-phone-mcp
~/.venvs/erius-phone-mcp/bin/pip install erius-phone-mcp

This installs an erius-phone-mcp command at~/.venvs/erius-phone-mcp/bin/erius-phone-mcp. Use that absolute path asthe command in your client config: GUI apps such as Claude Desktop and Cursorusually don't see your venv's PATH. python -m erius_phone_mcp does the samething as running the command.

Configuration

The server is configured entirely through environment variables:

Getting an API key

Request access at https://eriusphone.com. During early access the ERIUSPHONE team sets up each account by hand. You'll receive your API key anddevice id(s) directly from us. If you signed up and haven't heard back, email[email protected]. The same key signs you in to the dashboard athttps://eriusphone.com/dashboard/, which shows your devices live.

Treat the key like a password: anyone who has it can control your device.

Important: MCP clients start this server as a subprocess, and theygenerally do not pass along variables you export in your shell. Putthe variables in the client's env block, as shown below.

Add it to your MCP client

In every example, replace the key and device id with your own. If youinstalled with pip instead of using uvx, replace "command": "uvx", "args": ["erius-phone-mcp"] with "command": "/home/you/.venvs/erius-phone-mcp/bin/erius-phone-mcp".

Claude Code

claude mcp add erius-phone \
  -e ERIUS_PHONE_API_KEY=your-api-key \
  -e ERIUS_PHONE_DEFAULT_DEVICE=your-device-id \
  -- uvx erius-phone-mcp

Add -s user to make the server available in all your projects, or-s project to write it to a shared .mcp.json. Don't commit your key to ashared .mcp.json. Claude Code expands ${VAR} references in that file, soyou can keep the key in an environment variable instead:

{
  "mcpServers": {
    "erius-phone": {
      "command": "uvx",
      "args": ["erius-phone-mcp"],
      "env": {
        "ERIUS_PHONE_API_KEY": "${ERIUS_PHONE_API_KEY}",
        "ERIUS_PHONE_DEFAULT_DEVICE": "your-device-id"
      }
    }
  }
}

Run /mcp inside Claude Code to check that erius-phone is connected.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config). OnmacOS it's in ~/Library/Application Support/Claude/; on Windows it's in%APPDATA%\Claude\.

{
  "mcpServers": {
    "erius-phone": {
      "command": "uvx",
      "args": ["erius-phone-mcp"],
      "env": {
        "ERIUS_PHONE_API_KEY": "your-api-key",
        "ERIUS_PHONE_DEFAULT_DEVICE": "your-device-id"
      }
    }
  }
}

If Claude Desktop can't find uvx, put its absolute path in command(which uvx). Fully quit and reopen Claude Desktop after editing.

Cursor

Put the same mcpServers block in ~/.cursor/mcp.json to use it in allprojects, or in .cursor/mcp.json for one project. Then enable erius-phoneunder Cursor Settings → MCP.

Any other MCP client

The server speaks MCP over stdio. Point your client at uvx erius-phone-mcp, or at the erius-phone-mcp executable, and pass theenvironment variables above.

Tools

Every tool that acts on a device takes an optional device argument. If youleave it out, the tool uses ERIUS_PHONE_DEFAULT_DEVICE.

Account and devices

Seeing the screen

Acting on the screen

Apps

Quick example

Once the server is connected, ask your agent in plain language, e.g."List my ERIUS devices, go to the home screen, and open Contacts." Here's whathappens under the hood. The outputs below are real, lightly trimmed.

1. Find your device. The agent calls list_devices:

{"devices": [
  {"id": "vanilla", "description": "redroid Android 13, no Google services", "state": "device",
   "bootCompleted": true, "android": "13", "sdk": 33, "screen": {"width": 720, "height": 1280}},
  {"id": "tablet1", "form": "tablet", "description": "redroid Android 13 (vanilla, tablet)", "state": "device",
   "bootCompleted": true, "android": "13", "sdk": 33, "screen": {"width": 1600, "height": 2560}}
]}

2. Go home and look at the screen. press_key(key="home", device="vanilla")returns {"ok": true}, then snapshot(device="vanilla") returns theforeground app plus this tree:

- Group
  - ScrollView [ref=1]
    - Group
      - AppWidgetHostView (Search)
        ...
      - Text [ref=4] "Gallery" (Gallery)
  - View (Home)
  - Group
    - Text [ref=5] "Contacts" (Contacts)
    - Text [ref=6] "WebView Browser Tester" (WebView Browser Tester)
    - Text [ref=7] "Camera" (Camera)

3. Tap something. tap(device="vanilla", ref="5"), tap(device="vanilla", text="Contacts") and tap(device="vanilla", x=102, y=1116) all open Contactsand return {"ok": true}. After any action, take a fresh snapshot, becauserefs are only valid until the next one.

4. Check the result. foreground(device="vanilla") now reports theContacts app, and screenshot(device="vanilla") returns the screen as animage your agent sees directly.

Installing an APK for QA works the same way:

install_apk(device="vanilla", apk_path="/path/to/app.apk")
→ {"ok": true, "package": "com.erius.dashtest", "versionName": "1.0", "label": "ERIUS Dash Test",
   "adbOutput": "Performing Streamed Install\nSuccess", "ms": 94, ...}

Tips and limits

• Errors are passed through. If the API refuses an action, the tool callfails with the API's error code and message, e.g. HTTP 404: SelectorNotFound ... nothing on screen matches {"text": "..."} or HTTP 422: no_launcher_activity. The agent can read the message and adjust.
• Typing needs a ready field. Keystrokes sent while a field is stillopening are lost. If tapping a field opens a new screen (as AndroidSettings' search does), tap it, wait with snapshot/wait_for_text, thencall type_text without a target. Check the result with snapshot.
• ASCII-only typing. type_text supports printable ASCII only (an adblimitation): no emoji, accented characters or non-Latin scripts.
• Scroll by container. scroll needs the ref of the scrollable container(a ScrollView/List line in the snapshot). If the container has no ref,use swipe.
• Screenshots cost context. A phone screenshot (720×1280) is ~50–700 KB;a tablet screenshot (1600×2560) can be several MB. Prefer snapshot (text,much smaller) and take screenshots only when you need pixels.
• install_apk reads a local file. The path is on the machine runningerius-phone-mcp, not on the phone. The APK is streamed from disk anduploaded in full on each call.
• One server process = one API key. To use several accounts, add severalserver entries with different names and keys.
• Rate limits. The API allows about 30 requests per second per IP andqueues at most 8 requests per device; beyond that you get HTTP 429.

Troubleshooting

• ERIUS_PHONE_API_KEY is not set: the variable didn't reach the serverprocess. Put it in the client's env block, not just your shell. The serveralso prints a warning about this on stderr at startup, which shows up in yourclient's MCP logs.
• no device id given and ERIUS_PHONE_DEFAULT_DEVICE is not set: passdevice= in the tool call or set ERIUS_PHONE_DEFAULT_DEVICE. list_devicesshows your ids.
• HTTP 401: the key is wrong or revoked. HTTP 403: the device id doesn'texist or isn't on your account. Run whoami to see which devices your keycan use.
• HTTP 503 device_offline: the device is restarting. Retry shortly.
• could not reach the ERIUS PHONE API at ...: the URL is wrong, or the APIis unreachable from your machine. Check ERIUS_PHONE_API_URL, and raiseERIUS_PHONE_TIMEOUT if you're on a slow link.

License

MIT. The full license text is in the LICENSE file shipped with the package.