mcpField
G
Ghost in the Droid

Ghost in the Droid

本地服务
github.com/ghost-in-the-droidAI 与智能体40311 周前更新

关于 Ghost in the Droid

Ghost in the Droid 是一个开源 Python 框架,让任意 LLM Agent 通过 ADB 或 Appium/WebDriverAgent 控制真实的 Android 手机和 iPhone。它面向需要自动化移动应用、并希望复用技能的开发者和团队,并提供 62 个 MCP 工具。

主要功能

  1. 01通过 ADB 控制 Android 设备
  2. 02通过 WebDriverAgent 控制 iOS 设备
  3. 03实时屏幕串流与点击操作
  4. 04可复用的 YAML 与 Python 技能
  5. 05多设备任务队列与定时执行

适用场景

  1. 01让 Claude Code 等 MCP 客户端直接操作真实手机
  2. 02用固定技能重放已知的应用操作流程,无需调用 LLM
  3. 03在手机农场中批量运行移动应用自动化任务

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"ghost-in-the-droid-android-agent": {
"command": "uvx",
"args": [
"ghost-in-the-droid"
]
}
}
}
启动命令uvx ghost-in-the-droid

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
pypighost-in-the-droid1.3.2

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

幽灵正在轻点手机

Ghost in the Droid

召唤一只幽灵进入你的手机。
它看得见屏幕,会点击按钮,而且永不休眠。

网站 · 文档 · 技能中心 · 发布版本

许可证:MIT Python 3.10+ 62 个 MCP 工具 Android + iOS 云端或设备端 MCP Toplist:跻身前 1%(共 9.5 万项)


Ghost 正在操控九台真实手机

▶ 在 YouTube 上观看带声音的完整高清版 · 下载 mp4

九个 Agent。九台真实设备。一只幽灵。(点击观看。)


一句话介绍

每个 AI Agent 都会思考。几乎没有哪个能操作手机。

Ghost 就是身体。 它为任何大模型 Agent 提供一台真实的 Android 手机或 iPhone:通过简洁的工具界面读取屏幕、点击、滑动和输入,还能从你桌上的一台设备扩展到整座手机农场。让 Claude Code、Codex、Antigravity、Cursor、你的 LangChain 应用,或运行在手机本身内部的模型连接到它,你的 Agent 就有了双手。

自带大脑,身体始终如一。MIT 许可,永远开源。


自由组合:Ghost 矩阵

Ghost 1.3 是唯一一个平台、大脑和驱动程序都可替换的 Android + iOS Agent 框架。每列选一个,它们都能组合使用。

选择平台选择大脑选择驱动程序
Android,通过 USB ADBClaude Code(使用 Max/Pro 订阅即可免费)MCP 客户端(Claude Code、Codex、Antigravity、Cursor、Opencode)
Android,通过 Wi-Fi ADBAnthropic APILangChain 工具包
Android,使用 Docker + KVM 模拟器池OpenRouter(任意模型,一个密钥)LlamaIndex 工具规范
iPhone,通过 Appium + WebDriverAgentOllama(完全本地运行)Ghost CLI(ghost "book a table" --device pixel)
iPhone,通过 Tailscale + WebDriverAgent(无线)vLLM(使用你自己的 GPU)Web 仪表板,通过实时手机画面进行聊天
设备端 — llama.cpp(.gguf,任意量化版本)、MediaPipe(.task、Gemma 移动端模型包)、MLX(Apple Silicon,可选启用)。模型在手机内部运行,飞行模式下也能使用REST API(/docs OpenAPI)

Docker + KVM 模拟器池仅支持 Android;iOS 使用 Apple 自带的模拟器和 Xcode 签名,这些功能原生支持 macOS。

无论接入什么,大脑背后的身体始终提供相同的 62 个 MCP 工具。每次模型发布更新,都能免费升级你的手机 Agent。


效果演示

九段演示,每项功能一段,均在真实设备上录制。点击任意视频即可查看完整 MP4。

MCP 客户端:让你的 Agent 操控手机
Claude Code 操控手机
Claude Code:在 TUI 中输入,观看它操控手机。
Codex 操控手机
Codex:OpenAI 的命令行工具通过 MCP 操控真实手机。
Antigravity 操控手机
Antigravity:Google 的 Agent,同样具备 62 种工具。
接口:命令行、框架、浏览器
Ghost CLI 单行命令
Ghost CLI:ghost "check reddit" --device asus。
LangChain 适配器
LangChain:在框架 Agent 中使用 Ghost 的工具。
网页聊天操控手机
网页聊天:在浏览器中聊天,由它操控真实手机。
设备端与 iOS:手机既是身体,也是大脑
设备端 Android
设备端 Android:模型在应用中运行,支持飞行模式。
设备端 iPhone
设备端 iPhone:你的 iPhone 与自己对话。
iPhone 操控真实应用
iPhone,真实应用:Ghost 完成 Duolingo 课程。

功能介绍

用于通过一个 Agent 框架控制 Android 和 iOS 设备的开源 Python 框架。Android 通过 ADB 运行。iOS 通过 Appium XCUITest 和 WebDriverAgent 运行,以真实 iPhone 为目标路径,并使用模拟器进行开发和 CI。

为任意应用定义技能,从仪表板或 API 运行,并扩展到整个手机集群。

幽灵会帮你点按

  • 通过 ADB 控制 Android:点按、滑动、输入、剪贴板、Shell、Intent 和隐身变体
  • 通过 WebDriverAgent 控制 iOS:屏幕截图、无障碍树、点按、滑动、输入、启动应用、剪贴板、浏览器操作
  • 实时手机屏幕流:Android MJPEG/WebRTC、iOS WDA MJPEG,并提供屏幕截图回退方案
  • 在屏幕流上通过触摸进行交互式点按
  • 多设备手机集群,配备每台设备专属的作业队列

为任意应用打造可复用技能

  • 基于 YAML 的应用 UI 元素定义
  • 使用 elements.yaml 定义 Android 平台专属选择器,使用 elements_ios.yaml 定义 iOS 平台专属选择器
  • 带前置条件检查的 Python 操作类
  • 将多个操作串联起来的多步工作流
  • 内置 TikTok 和 Play Store 技能
  • iOS 浏览器/新闻演示技能和冒烟级 TikTok iOS 工作流
  • Skill Hub:在社区注册表中浏览、搜索和安装技能
  • 通过 CLI 安装:android-agent skill install tiktok

教幽灵新把戏

  • 基于 BFS 的应用自动探索器:发现每个屏幕和转换
  • LLM 辅助的技能创建器:一边查看实时设备流,一边与 AI 聊天
  • AI 识别 UI 元素并生成操作/工作流代码

扩展闹鬼规模

  • 多设备手机集群,配备每台设备专属的作业队列
  • Bot 运行器:对自动化作业进行排队、安排和监控
  • 按设备运行集成测试,并录制 Android 屏幕或 iOS WDA MJPEG
平台支持
接入界面AndroidiOS
设备引用ADB 序列号,例如 emulator-5554ios:<udid>
后端ADB + 可选的 Portal 配套应用Appium XCUITest + WebDriverAgent
真实设备支持支持支持,需 Mac/Xcode/WDA 签名
模拟器支持Android 模拟器工具通过 Appium/WDA 启动的 iOS 模拟器
实时流Portal WebRTC、MJPEG、屏幕捕获WDA MJPEG,或回退到屏幕截图轮询
屏幕树Android UIAutomator XML规范化的 XCTest 无障碍树
技能elements.yaml、Android 软件包elements_ios.yaml、iOS Bundle ID
目前仅支持 AndroidADB Shell、Intent、无线 ADB、Play Store 助手、Portal 覆盖层不支持,并提供稳定的平台错误信息

为什么这样构建

技能成本为 $0。思考需要消耗 Token。 Agent 不应该为了点按已经点过一千次的按钮而调用大模型。已知工作流会编译为技能:确定性的 YAML + Python 方案,可在几秒内重放,且不调用大模型。未知任务交给 AI,已知任务直接重放。

手机是最容易使用的沙盒。 给幽灵一台配有专属 SIM 卡和账户的旧 Android 手机,与自己的生活物理隔离。你已经知道如何设置手机。

默认不安装应用。 全新安装不会触碰 Android 设备上的任何内容:屏幕读取通过 uiautomator 完成,操作通过 adb shell input 完成,无需 Root,也不需要无障碍服务。想要更快?可选的 Portal 配套应用能让 UI 读取速度提升约 30 倍。想要保护隐私?设备端模式会在手机内运行整个流程,不会有任何内容离开手机。所有功能均需主动选择启用。

本地优先,云端可选。 服务和仪表板都运行在你的设备上。使用本地或设备端大脑时,屏幕截图绝不会离开你的网络。选择云端大脑后,提示词会像使用任何工具一样发送给对应的服务商。始终由你决定。

要求

  • Python 3.10+
  • Android:启用 USB 调试的 Android 手机,且 adb 已加入 PATH(adb devices 应能列出你的手机)
  • iOS:安装了 Xcode 的 macOS、Appium 2 + XCUITest 驱动,以及已信任的 iPhone 或已启动的模拟器
  • Node.js 18+(用于前端开发服务器)

iOS 支持

Ghost 通过 Appium/WebDriverAgent 驱动 iPhone,并提供相同的工具 接口:ios:<udid> 设备引用会将 tap/swipe/type/screenshot 路由到 WDA,而 支持 iOS 的浏览器基础工具(open_url、read_news、extract_visible_text) 则可用于网页任务。仅限 Android 的工具(shell、launch_intent、Portal overlay) 会返回明确的平台错误,而不会静默失败。

iOS 默认不启用:设置 GITD_ENABLE_IOS=1(或在 .env 中设置 ios_platform_enabled=true) 即可启用。无线控制通过你的 Tailscale tailnet 进行,因此请将 tailnet 视为 信任边界。Appium/WDA 设置请参阅 docs/SETUP_IOS.md,要在 iPhone 本机运行模型,请参阅 on-device on iPhone。


快速开始

使用 uvx(或 pipx)即可零安装运行:

uvx ghost-in-the-droid doctor   # green/red preflight: python, adb on PATH, devices, ports, LLM keys
uvx ghost-in-the-droid login    # sign in with your Claude subscription, no API key needed
uvx ghost-in-the-droid up       # server + dashboard at http://localhost:5055  (API docs at /docs)

当缺少某项内容(例如 adb 未加入 PATH)时,doctor 会打印包含修复提示的检查清单,而不是堆栈跟踪。更喜欢使用 pipx?运行 pipx install ghost-in-the-droid 即可获得 ghost-in-the-droid / android-agent 命令。

使用 Claude 订阅登录(无需 API 密钥)

如果你有 Claude Max/Pro 订阅,就不需要 API 密钥。android-agent login 会通过 claude CLI 自带的 Anthropic OAuth 流程为你登录,并将 Ghost 指向 claude-code 提供方:

android-agent login       # opens Anthropic sign-in via the claude CLI

Ghost 从不处理或存储你的令牌;令牌由 claude CLI 管理,包括刷新。登录后,doctor 会显示绿色的 Claude subscription 检查项。若要改用 API 密钥,请设置 ANTHROPIC_API_KEY(或 OPENAI_API_KEY / OPENROUTER_API_KEY),并选择相应的提供方。

使用 Ollama 完全本地运行(无需密钥,无需云服务)

在 Phone Agent 选项卡中选择 Ollama。所有运行都在你的计算机上完成,需使用 Ollama:

brew install ollama       # or: curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull llama3.2:3b   # 2GB, fast, good tool-use
从克隆的仓库开始(用于开发)
git clone https://github.com/ghost-in-the-droid/android-agent.git
cd android-agent
pip install -e ".[all]"

android-agent doctor        # preflight
android-agent up            # start server + dashboard on :5055

# Frontend (separate terminal)
cd frontend && npm install && npx vite --host 0.0.0.0 --port 6175
# Dashboard at http://localhost:6175
iOS 快速开始

iOS 支持需要 Mac,因为 Appium 使用 Xcode 的 XCUITest/WebDriverAgent 技术栈。真机 iPhone 还需要进行信任验证、启用开发者模式、按提示授予 UI Automation 权限,并使用 Apple 开发团队对 WDA 进行签名。

# 1. Install and run Appium XCUITest
npm install -g appium
appium driver install xcuitest
appium --base-path /

# 2. Find your iPhone or booted simulator UDID
xcrun xctrace list devices
xcrun simctl list devices booted

# 3. Configure the backend for iOS
export IOS_DEVICE_UDID="<udid>"
export IOS_APPIUM_URL="http://127.0.0.1:4723"
export IOS_BUNDLE_ID="com.google.chrome.ios"       # or com.apple.mobilesafari
export IOS_MJPEG_SERVER_PORT="9100"                # use unique ports per iOS device

# 4. Run a product-path smoke workflow
uv run python scripts/ios_chrome_news_smoke.py \
  --device "ios:<udid>" \
  --bundle-id "$IOS_BUNDLE_ID" \
  --url https://text.npr.org/ \
  --max-headlines 5 \
  --max-articles 3 \
  --fix-health \
  --out-dir data/ios_chrome_news_smoke

有关真机完整签名、模拟器、WDA MJPEG、健康状态恢复、调度器和 MCP 设置的详细信息,请参阅 docs/SETUP_IOS.md。

环境变量

将 .env.example 复制为 .env(如果提供了该文件),或在项目根目录创建 .env 文件。服务器通过 Pydantic Settings 读取配置。可选变量包括:

变量用途
OPENAI_API_KEY大模型功能(Skill Creator、Agent Chat)
ANTHROPIC_API_KEY备用大模型提供方
OPENROUTER_API_KEYOpenRouter 大模型提供方
DEFAULT_DEVICEADB 序列号(为空时自动检测)
IOS_DEVICE_UDIDiPhone 或模拟器 UDID;设备地址格式为 ios:<udid>
IOS_APPIUM_URLAppium 服务 URL,默认为 http://127.0.0.1:4723
IOS_BUNDLE_ID默认 iOS 应用/浏览器 bundle,例如 com.google.chrome.ios 或 com.apple.mobilesafari
IOS_DEVICES_JSON多部手机/模拟器的逐设备 iOS 配置,包含 WDA 端口、bundle ID 和 MJPEG 端口
IOS_MJPEG_SERVER_PORTWDA MJPEG 流端口;每台 iOS 设备使用一个唯一端口

为任意 AI Agent 装上移动设备的身体(MCP)

Ghost 附带一个 MCP 服务,提供 62 个工具,用于控制真实设备。任何兼容 MCP 的客户端都可以使用这些工具。Android 序列号会使用 Android 实现;ios:<udid> 引用会在支持的情况下路由到 iOS 后端,对于仅支持 Android 的工具,则会返回稳定的“不支持该平台”错误。只需一条命令即可完成接入:

# Claude Code (same shape for Codex, Cursor, VS Code Copilot, Windsurf)
claude mcp add android-agent -- uvx --from ghost-in-the-droid android-agent-mcp

uvx 会安装软件包、构建隔离环境并运行服务。无需克隆仓库,也无需创建 venv。

其他客户端(Codex、Claude Desktop、Cursor、VS Code、Windsurf)
# Codex (OpenAI)
codex mcp add android-agent -- uvx --from ghost-in-the-droid android-agent-mcp

Claude Desktop(claude_desktop_config.json)、Cursor(.cursor/mcp.json)、Windsurf(mcp_config.json):

{
  "mcpServers": {
    "android-agent": {
      "command": "uvx",
      "args": ["--from", "ghost-in-the-droid", "android-agent-mcp"]
    }
  }
}

VS Code Copilot(.vscode/mcp.json)在 "servers" 键下使用相同的配置块。克隆仓库的贡献者会获得一份可直接使用的 .mcp.json,首次启动 claude 时,全部 62 个工具即可使用。

62 个工具,按类别划分:

类别Ghost 可以做什么
查看screenshot、get_elements、get_screen_tree、get_screen_xml、screenshot_annotated、screenshot_cropped
触控tap、tap_element、swipe、long_press、type_text、type_unicode、press_back、press_home、press_key
应用launch_app、search_apps、list_apps、launch_intent、force_stop、list_packages
理解get_phone_state、classify_screen、find_on_screen、ocr_screen、ocr_region、extract_visible_text
浏览器 / iOSopen_url、browser_back、get_current_url、read_news、extract_articles、wait_for_text
设备list_devices、clipboard_get、clipboard_set、get_notifications、open_notifications、toggle_overlay、device_health
技能list_skills、run_workflow、run_action、create_skill、explore_app
批处理run_flow / chain:一次调用即可在服务端运行完整的多步流程,将 N 次往返压缩为 1 次
诊断list_crashes、get_crash、web_search、屏幕录制、相机 + TTS

toggle_overlay、launch_intent、Android shell 辅助工具、无线 ADB 和 Play Store 辅助工具仍仅支持 Android,在 iOS 上会返回稳定的平台错误。


在手机内运行大脑

1.3 版新增:模型可以运行在设备上。Ghost 配套应用内置了真实的推理引擎,因此手机既是身体,也是大脑。开启飞行模式后,Agent 仍能工作,所有数据都不会离开设备。

平台引擎模型格式最适用场景
Androidllama.cpp(JNI).gguf任意 GGUF:Gemma、Llama、Mistral、Qwen、DeepSeek
AndroidMediaPipe.task小型 Gemma 模型,Android 集成速度最快
iPhonellama.cpp(Metal).gguf与 Android 使用相同的 GGUF,Qwen2.5 1.5B 可在 Metal 上运行
iPhoneMLXApple Silicon在新款芯片上实现更快的解码,可选择启用

在 iPhone 上,Qwen2.5 1.5B 通过 Metal 上的 llama.cpp 运行,并操控手机自身的 UI;还可选择启用 MLX 引擎,以便在 Apple Silicon 上加快解码速度。小型模型通过语法约束解码确保输出可靠,从而始终能正确解析工具调用。详情请参阅设备端 LLM 页面。


Skill Hub 命令行工具

android-agent skill search tiktok        # search the public registry
android-agent skill install tiktok       # install a skill
android-agent skill install github.com/someone/their-skill
android-agent skill list                 # what is installed
android-agent skill update tiktok        # update a skill
android-agent skill validate ./my-skill/ # check before publishing

技能注册表位于本仓库的 registry/ 中。系统每晚会自动发现标记为 android-agent-skill 的仓库中的社区技能。

教幽灵使用新应用

创建技能有两种方式:

社区技能(你自己的仓库):创建一个包含 skill.yaml、elements.yaml、操作和工作流的仓库,为其添加 android-agent-skill 标签,它就会自动出现在 Skill Hub 中(每晚抓取一次)。

官方技能(向此仓库提交 PR):先将其构建并测试为社区技能,然后提交 PR,将其添加到 registry/。CI 会进行验证,维护者会审核,之后它就会获得“Official”徽章。

每项技能都需要:

  • skill.yaml:元数据(名称、版本、应用包名或 iOS bundle ID、支持的平台、操作、工作流)
  • elements.yaml:Android UI 元素资源 ID 和描述
  • elements_ios.yaml:可选的 iOS 选择器,用于 XCTest 无障碍树
  • actions/:继承 Action 并实现 precondition() 和 execute() 的 Python 类
  • workflows/:继承 Workflow 并实现 steps() 的 Python 类

想让 AI 来做?Skill Creator 会监控实时设备流,并在你讲述时生成操作和工作流代码。完整指南请参阅 CONTRIBUTING.md。


控制面板

本地优先的控制室,地址为 http://localhost:5055(开发环境中为 :6175)。提供 WebRTC 和 MJPEG 实时流、屏幕点按、跟踪,以及下表中的所有标签页。

标签页功能
Phone Agent设备实时流(MJPEG/WebRTC)、屏幕点按/滑动、多设备视图
Scheduler类 Cron 的作业调度与队列管理
Skill Hub浏览已安装的技能、运行操作和工作流、导出/删除
Skill Creator借助 LLM 的技能构建器,支持设备实时流
Skill Miner自动应用探索器:通过 BFS 发现状态并截图
Manual Run启动/停止机器人作业、队列管理、日志
Tests按设备运行测试并回放屏幕录制
Emulators创建、启动、创建快照并管理 Android 模拟器
Tracing每轮跟踪、令牌统计、工具调用可见性

架构

android-agent/
  run.py                    # Uvicorn entry point on :5055
  gitd/
    app.py                  # FastAPI app factory + plugin hook
    models/  schemas/       # SQLAlchemy 2.0 ORM + Pydantic v2
    routers/  services/     # Route handlers + business logic
    skills/                 # Skill packages (tiktok, play_store, safari [iOS], tiktok_ios)
    bots/common/adb.py      # Android Device class: tap, swipe, dump tree, wait_for
    bots/common/ios.py      # iOS Device class: Appium/WDA session, UI tree, gestures
    mcp_server.py           # MCP server: 62 tools for any LLM agent
  frontend/                 # Vue 3 + Vite + TypeScript + Tailwind
  portal/                   # Kotlin companion app (WebRTC, on-device inference)
  site/                     # Docs site (Astro + Starlight)

工作流程: :5055 上的 FastAPI 后端提供设备控制、技能、机器人、调度和流媒体功能。Vue SPA 通过 /api/* 与其通信。技能定义各应用的交互方式(元素 + 操作 + 工作流)。设备后端根据引用路由:纯序列号使用 bots/common/adb.py,ios:<udid> 引用使用 bots/common/ios.py 和 Appium/WDA。状态通过 SQLAlchemy 2.0 和 Alembic 存储在 SQLite 中。

基准测试(抢先预览)

早期结果,完整的方法说明仍在编写中:由 Claude Code 驱动时,Ghost 在未经修改的上游测试框架上完成了 AndroidWorld 中的 116 项任务中的 115 项(99.1%)。请将其视为预览结果,而非可引用的数据。详细说明和执行轨迹即将发布。请关注 releases。


技术栈

层技术
后端FastAPI、Uvicorn、Python 3.10+
数据SQLAlchemy 2.0、Alembic、Pydantic v2、SQLite(WAL)
前端Vue 3、TypeScript、Vite、Tailwind CSS 4
设备控制Android 使用 ADB;iOS 使用 Appium XCUITest/WebDriverAgent
流媒体Android 通过 Portal 提供 MJPEG/WebRTC;iOS 使用 WDA MJPEG,并在必要时回退到截图
设备端llama.cpp、MediaPipe(Android);iOS 使用 Metal 上的 llama.cpp、MLX
质量Ruff、pytest、Playwright

运行测试

大多数测试都是单元/API 测试,无需连接实时设备即可运行。实时 Android 和 iOS 集成测试需要相应的设备环境。

# Run all tests on a specific device
DEVICE=<serial> python3 -m pytest tests/ -v --tb=short

运行 iOS 实时冒烟测试:

IOS_LIVE_NEWS_TEST=1 \
IOS_DEVICE_UDID="<udid>" \
IOS_APPIUM_URL="http://127.0.0.1:4723" \
IOS_BUNDLE_ID="com.google.chrome.ios" \
uv run --extra test python -m pytest tests/test_browser_news.py::test_live_ios_chrome_news_workflow

使用 adb devices 获取 Android 设备序列号。


数据库迁移

项目使用 Alembic 进行架构迁移:

alembic revision --autogenerate -m "add new_field to my_table"   # after editing a model
alembic upgrade head                                              # apply pending
alembic downgrade -1                                              # rollback one

贡献

每项技能都会让 ghost 变得更强大。有关添加应用技能(影响最大)、编写操作和工作流、后端架构及 PR 流程,请参阅 CONTRIBUTING.md。欢迎在 Skill Hub 加入社区。


许可证

MIT。ghost 是免费的。ghost 是开源的。ghost 属于你。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。