ERIUS PHONE

erius-phone-mcp

一个 MCP 服务，可将你的 ERIUS PHONE 设备变成适用于 Claude Code、 Claude Desktop、Cursor 或任何其他 MCP 客户端的原生工具。ERIUS PHONE 设备是一部专供你的 Agent 使用的真实 Android 手机或平板电脑。连接此服务后，你的 Agent 可以：

• 列出设备
• 以无障碍树或屏幕截图的形式读取屏幕
• 点击、长按、输入、滑动和滚动
• 启动和停止应用、打开 URL 并发送 Intent
• 安装和卸载 APK
• 获取崩溃日志

Agent 可直接操控设备。你无需编写任何胶水代码。

**早期访问：**此软件包处于 1.0 之前版本（0.2.0）。1.0 发布前，工具名称和 参数仍可能发生变化。

要求

• Python 3.10+
• ERIUS PHONE API 密钥。请在 https://eriusphone.com 注册；参见下文的“获取 API 密钥”。

安装

选项 A：uvx（无需安装步骤）。如果你已安装 uv，MCP 客户端可以通过 uvx erius-phone-mcp 启动服务。uv 会获取此软件包，并将其保存在自己的 环境中。下方的客户端配置示例使用此方式。

选项 B：pip，安装到独立的虚拟环境中，避免依赖项与其他 Python 项目 发生冲突：

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

此操作会在 ~/.venvs/erius-phone-mcp/bin/erius-phone-mcp 安装 erius-phone-mcp 命令。在客户端配置中，将此绝对路径用作 command：Claude Desktop 和 Cursor 等图形应用通常无法读取虚拟环境的 PATH。运行 python -m erius_phone_mcp 与运行该命令效果相同。

配置

此服务完全通过环境变量进行配置：

变量	必填	说明
ERIUS_PHONE_API_KEY	是	你的 ERIUS PHONE API 密钥。每个请求都会使用此密钥进行身份验证，并限定在你的账户范围内。
ERIUS_PHONE_DEFAULT_DEVICE	否	工具调用未指定设备时使用的设备 ID（例如 vanilla）。未设置时，Agent 会在每次调用时传入 device；list_devices 会显示设备 ID。
ERIUS_PHONE_API_URL	否	API 基础 URL。默认为 https://api.eriusphone.com；只有在我们提供了其他地址时才设置此项。
ERIUS_PHONE_TIMEOUT	否	每个请求的 HTTP 超时时间，单位为秒。默认为 30。

获取 API 密钥

请通过 https://eriusphone.com 申请访问权限。早期访问期间，ERIUS PHONE 团队会手动为每个账户完成设置。我们会直接向你提供 API 密钥和设备 ID。如果你已注册但尚未收到回复，请发送邮件至 [email protected]。你也可以使用同一个密钥登录 https://eriusphone.com/dashboard/，实时查看设备。

请像对待密码一样保护此密钥：任何持有密钥的人都可以控制你的设备。

重要提示：MCP 客户端会将此服务作为子进程启动，通常不会传递你在 Shell 中通过 export 设置的变量。请将变量放入客户端的 env 块中，如下方所示。

将其添加到 MCP 客户端

在每个示例中，将密钥和设备 ID 替换为你自己的值。如果你使用 pip 安装，而非使用 uvx，请将 "command": "uvx", "args": ["erius-phone-mcp"] 替换为 "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

添加 -s user 可让所有项目使用此服务；添加 -s project 可将其写入共享的 .mcp.json。不要将密钥提交到共享的 .mcp.json。Claude Code 会展开该文件中的 ${VAR} 引用，因此你可以将密钥保存在环境变量中：

{
  "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"
      }
    }
  }
}

在 Claude Code 中运行 /mcp，检查 erius-phone 是否已连接。

Claude Desktop

编辑 claude_desktop_config.json（Settings → Developer → Edit Config）。在 macOS 上，文件位于 ~/Library/Application Support/Claude/；在 Windows 上，位于 %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"
      }
    }
  }
}

如果 Claude Desktop 找不到 uvx，请将其绝对路径填入 command （which uvx）。编辑后，完全退出并重新打开 Claude Desktop。

Cursor

将相同的 mcpServers 配置块放入 ~/.cursor/mcp.json，即可在所有 项目中使用；若只用于一个项目，则放入 .cursor/mcp.json。然后在 Cursor Settings → MCP 下启用 erius-phone。

其他 MCP 客户端

该服务通过 stdio 使用 MCP 通信。将客户端指向 uvx erius-phone-mcp 或 erius-phone-mcp 可执行文件，并传入上述 环境变量。

工具

每个操作设备的工具都接受一个可选的 device 参数。如果 省略该参数，工具将使用 ERIUS_PHONE_DEFAULT_DEVICE。

账号和设备

工具	描述
whoami	此服务正在使用的账号和密钥，以及它可以访问的设备 ID。可用于快速检查密钥是否有效。
list_devices	密钥可以访问的所有设备及其实时状态（已启动、Android 版本、屏幕尺寸）。
get_device	单台设备的完整状态，包括当前位于前台的应用。

查看屏幕

工具	描述
snapshot	当前屏幕的无障碍树快照：每个可见元素及其文本、角色和 ref，可将 ref 传给 tap/type/scroll。每次生成快照时，ref 都会重置。
screenshot	以 MCP 图片内容形式返回屏幕，让模型直接查看。默认格式为 JPEG，最长边为 1024 px（几十 KB）。format、quality、max_side 和 scale 可更改这些设置；format="png", max_side=null 可生成全尺寸 PNG（手机上约 3 MB）。文本行会显示图片和屏幕尺寸。
foreground	仅返回前台应用（包名、Activity）以及是否显示崩溃对话框。
wait_for_text	等待屏幕上出现指定文本，最长等待 timeout_ms（最大值为 120000）。返回检测到文本时的快照。

操作屏幕

工具	描述
tap	通过 ref、可见的 text/content_desc 或原始 x、y 像素坐标点击。
long_press	通过 ref、text/content_desc 或 x、y 长按（可选按住时间 ms）。
type_text	在字段中输入文本。可先点击 ref/text_target，清空字段，并在之后按 Enter。
press_key	back、home、enter、delete、tab、escape、up、down、left、right、space、power、volup、voldown、recent、menu、wakeup 或数字键码。
swipe	在设备像素坐标中的两点之间滑动。
scroll	向上/下/左/右滚动容器。传入 ScrollView/List 本身的 ref，而不是其中某一行的 ref。

应用

工具	描述
launch_app	按包名启动已安装的应用（例如 com.android.settings）。
open_url	打开 http/https/market URL，可选在指定应用中打开。
send_intent	使用任意 intent action 启动 Activity，例如 android.settings.WIFI_SETTINGS；还可选传入 data、package、component 和 extras。
stop_app	强制停止应用。
list_apps	列出已安装的应用；设置 third_party_only=True 仅列出用户安装的应用。
install_apk	从运行此服务的机器上的文件上传并安装 APK。返回包名、版本以及安装是否成功。
uninstall_app	按包名卸载应用。
get_crash_log	设备的崩溃日志缓冲区（logcat -b crash）。应用崩溃后使用此工具查看实际堆栈跟踪。

快速示例

连接服务后，可以用日常语言向你的 Agent 提出要求，例如： “列出我的 ERIUS 设备，返回主屏幕，然后打开联系人。” 以下是其背后的 执行过程。下面的输出均为真实输出，仅做了少量删减。

1. 查找设备。 Agent 调用 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. 返回主屏幕并查看屏幕。 press_key(key="home", device="vanilla") 返回 {"ok": true}，然后 snapshot(device="vanilla") 返回前台应用以及 以下视图树：

- 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(device="vanilla", ref="5")、tap(device="vanilla", text="Contacts") 和 tap(device="vanilla", x=102, y=1116) 都会打开联系人 并返回 {"ok": true}。每次操作后都要重新调用 snapshot，因为 refs 仅在下一次 调用前有效。

4. 检查结果。 foreground(device="vanilla") 现在会报告联系人 应用，而 screenshot(device="vanilla") 会返回 Agent 可直接查看的屏幕图像。

安装 APK 进行 QA 的方式也相同：

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, ...}

提示与限制

• 错误会直接传递。 如果 API 拒绝某项操作，工具调用会失败，并返回 API 的 错误代码和消息，例如 HTTP 404: SelectorNotFound ... nothing on screen matches {"text": "..."} 或 HTTP 422: no_launcher_activity。Agent 可以读取消息并调整操作。
• 输入文字需要字段就绪。 字段仍在打开时发送的按键会丢失。如果点击字段会打开新屏幕（例如 Android 设置中的搜索），请先点击，再通过 snapshot/wait_for_text 等待，然后 不指定目标调用 type_text。用 snapshot 检查结果。
• 仅支持输入 ASCII 字符。 type_text 仅支持可打印的 ASCII 字符（这是 adb 的限制）：不支持表情符号、带重音符号的字符或非拉丁文字。
• 按容器滚动。 scroll 需要可滚动容器的 ref（视图树中的 ScrollView/List 行）。如果容器没有 ref，请使用 swipe。
• 截图会占用上下文。 默认截图为 JPEG，最长边为 1024 px（几十 KB）。手机的全尺寸 PNG （1440×3120）约为 3 MB，超过许多 MCP 客户端单次工具结果所能接受的大小。优先使用 snapshot（文本，体积小得多），仅在需要查看像素时截取屏幕截图。
• 缩放截图中的坐标。 除非向 tap、long_press 或 swipe 传入你读取坐标所依据截图的尺寸 image_width 和 image_height，否则 x、y 均为设备像素。
• install_apk 会读取本地文件。 路径位于运行 erius-phone-mcp 的机器上，而非手机上。每次调用都会从磁盘读取 APK 并完整上传。
• 一个服务进程对应一个 API 密钥。 如需使用多个账户，请添加多个名称和密钥不同的服务条目。
• 速率限制。 API 每个 IP 每秒允许约 30 个请求，每台设备最多排队 8 个请求；超过限制会收到 HTTP 429。

故障排除

• ERIUS_PHONE_API_KEY is not set：该变量未传递到服务进程。请将其放入客户端的 env 块中，而不只是设置在 shell 里。服务启动时也会在 stderr 上打印相关警告，该警告会显示在客户端的 MCP 日志中。
• no device id given and ERIUS_PHONE_DEFAULT_DEVICE is not set：在工具调用中传入 device=，或设置 ERIUS_PHONE_DEFAULT_DEVICE。list_devices 会显示你的设备 ID。
• HTTP 401：密钥错误或已撤销。HTTP 403：设备 ID 不存在或不属于你的账户。运行 whoami 可查看你的密钥可用的设备。
• HTTP 503 device_offline：设备正在重启。请稍后重试。
• could not reach the ERIUS PHONE API at ...：URL 错误，或你的机器无法访问 API。请检查 ERIUS_PHONE_API_URL；如果网络连接较慢，请增大 ERIUS_PHONE_TIMEOUT。

许可证

MIT。完整许可证文本位于随软件包附带的 LICENSE 文件中。