ascript-mcp
Provides tools for automating Android devices including screen capture, UI tree analysis, OCR, color matching, project deployment, and device management through AScript API integration.
Provides tools for automating iOS devices (without jailbreak or signing) including screen capture, UI tree analysis, OCR, color matching, project deployment, and device management through AScript API integration.
Provides access to YOLO plugins through AScript's online plugin library for computer vision and object detection capabilities in device automation workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ascript-mcp scan for connected devices and show me the screen of the first Android phone"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ascript-mcp
Chinese | English
AScript MCP Service — Allows AI programming tools (Claude Desktop / Cursor / Trae) to directly query AScript API documentation and control real Android / iOS devices (iOS requires no signing or jailbreaking).
Features
API Documentation Query: Module overview, API search, code examples, and environment setup guides
Online Plugin Query: Real-time query of the AScript plugin library (OCR, YOLO, HID, LLMs, etc.)
Device Interaction: Screenshots, UI trees, OCR, color finding, color comparison, and selector testing
Development & Deployment: Create projects, upload code, run, stop, and view logs
Device Management: LAN scanning, ADB scanning, and automatic connection
Related MCP server: magic-api-mcp-server
Installation
pip install ascript-mcpConfiguring Cursor
1. MCP Configuration
Create .cursor/mcp.json in the project root directory:
{
"mcpServers": {
"ascript": {
"command": "python",
"args": ["-m", "ascript_mcp.local"]
}
}
}2. Rule Configuration
Copy the entire docs/AGENT_RULES.md into the .cursorrules (for Cursor) or CLAUDE.md / AGENTS.md (for Claude Code / other IDEs) in your automation project root.
This rule template includes:
5-stage standard workflow (Observe → Select Strategy → eval_python iteration → Crop if necessary → Upload and Run)
Decision tree for API selection (UI controls → OCR → Image search → Color search)
Orchestration examples for common tasks like auto-login, check-in, and game combat
Anti-pattern list (guessing code, running without verification, hardcoding non-existent image paths, etc.)
Simplified rules (use only if you don't want to copy the full rules):
当用户需要编写设备自动化脚本(Android/iOS/Windows)时,必须先调用 ascript MCP 的 get_device_status 与 list_python_packages,再用 eval_python 在设备 REPL 里 验证关键代码片段,最后才 upload_file + run_project。 禁止凭记忆编写 ascript 代码。
Tool List
API Documentation (5)
Tool | Description |
| Get platform API module overview |
| Get detailed module API documentation |
| Search for APIs by keyword |
| Get code examples |
| Get environment setup guide |
Online Plugins (2)
Tool | Description |
| Query plugin library list |
| Get detailed plugin documentation |
Device Connection (5)
Tool | Description |
| Automatically connect to devices from project configuration |
| Scan LAN + ADB devices |
| Manually connect to a specified device |
| Get full device running status (running mode/permissions/screen/battery/memory/running scripts, etc., Android only) |
| List third-party Python libraries installed on the AScript App (Android + iOS) |
Observation Interface (6)
Tool | Description |
| Capture device screen |
| Get UI control tree |
| Test if a selector matches |
| Screen text recognition |
| Multi-point color search |
| Multi-point color comparison |
Development & Deployment (7)
Tool | Description |
| Create a project on the device |
| Upload files to the device (automatically creates project) |
| Run project |
| Debug mode run (Android + ADB), automatically forwards port 5678 and returns VS Code attach configuration |
| Stop project |
| Get running logs |
| Device Python REPL (Android + iOS): Execute code directly in the main process to get results immediately, with a cycle of a few hundred milliseconds. Suitable for exploratory debugging, complex decision-making, and custom workflows (SoM/intelligent tap/auto-cropping templates, etc.). iOS automatically translates |
File Management (2)
Tool | Description |
| List projects on the device |
| Get project file tree |
Online SSE Mode
If you need to deploy as a public service (API documentation query only):
uvicorn ascript_mcp.server:app --host 0.0.0.0 --port 8000License
MIT License, see LICENSE for details. Copyright © 2026 Beijing Aoyue Technology Co., Ltd.
More Information
AScript Official Website: https://ascript.cn
API Documentation: https://docs.airscript.cn
Plugin Library: https://py.airscript.cn
Community Forum: https://bbs.ascript.cn
Beijing ICP Filing No. 2020040944-4
Available Tools
29 toolsauto_connectA
从当前 AScript 工程目录自动连接设备。 读取 .vscode/settings.json 中的 ascript.deviceId 和 ascript.platform,自动连接对应设备。 VSCode 插件创建工程时会保存这些信息,无需用户手动输入 IP。 传入当前工程的根目录路径即可。
Inputs: project_path (required).
compare_colorsB
多点比色:检查屏幕指定位置的颜色是否匹配。 返回布尔值。用于判断界面状态。
Inputs: colors (required), diff.
connect_deviceA
连接 Android/iOS 设备。连接后才能使用截图、控件树等设备工具。 局域网设备传 IP,ADB 设备传序列号并设 connection_mode='ADB'。
Inputs: ip (required), port, password, connection_mode.
create_projectA
在设备上创建新工程。上传文件前需要先创建工程。
Inputs: name (required).
deploy_and_runA
一步完成开发验证循环:上传代码 → 运行 → 收集日志 → 截图验证。 代码会上传为 init.py(入口文件),工程不存在时自动创建。 返回上传结果、运行结果、日志内容和运行后截图。
Inputs: project_name (required), code (required), log_seconds.
dump_ui_treeA
获取设备当前界面的控件树(UI 层级结构)。返回所有控件的 id、text、desc、className、rect、clickable 等属性。
【Android】调用前必须先调 get_device_status 确认 run_mode,再选对应 mode,否则拿空树:
run_mode.code=accessibility(无障碍模式)→ mode=0/1(简单/复杂),或 2/3(过滤系统层变种)
run_mode.code=root(Root 或激活模式) → mode=9(root 控件)
run_mode.code=hid(HID 控件 / 辅助控件模式)→ mode=6(辅助控件)
run_mode.code=screen_only(图色模式) → 无控件树,跳过 dump,走 OCR/找图 ⚠ Android 命名陷阱:code="hid" 实际是 ASS 枚举(辅助控件,有控件树);code="screen_only" 才是图色模式(无控件树)。 Selector 实例化要传相同的 mode:node.Selector(mode=<dump 的 mode>)。
【iOS】只有 WebDriverAgent 一套引擎,不接 mode 参数(传了被忽略),返回 WDA XML。iOS Selector() 也不接 engine mode;它的 MODE_EQUAL/CONTAINS/MATCHES 是给单个条件的匹配运算符(如 selector.text("x", mode=MODE_CONTAINS)),别和 Android 混。
【写 selector 必看】控件树里有 text/id/desc/className 等属性的元素,必须用 node.Selector() 通过属性定位操作,不要用坐标点击。坐标只用于控件树中确实没有任何可识别属性的元素。 Selector 实例化时也要传相同的 mode:node.Selector(mode=<dump 的同一个 mode>)。
Inputs: mode.
eval_pythonA
在设备主进程的 Python 上下文中直接 exec 任意代码,立即返回结果(Android + iOS)。 几百毫秒一轮,不需要 upload_file/run_project,适合:
探索性调试:试 selector / 找图 / OCR / 找色 / 一次点击
复合决策:把'看屏幕→判断→点击'打包一段 Python 一次执行
自动裁模板、SoM 标注、智能 tap 路由
任意一次性同步 API 调用:action.click / slide / Selector(任何 mode) / Permission / KeyValue / Sms / Clipboard 等
Android 主进程 client 已本地 stub 化(App.java onCreate 时 bindClient),所有原本走 :py 进程 IPC 的 API 现在 eval 里也能直接调。
⛔ 红线:eval 代码无法外部中断!HTTP 60s 超时只断客户端连接,服务端 Python 仍在跑直到自然返回;卡住 = 整个 App UI 冻住。所有循环必须 range/deadline 限定, sleep ≤ 5s,try/except 整段。超过 30s 的逻辑改用 upload + run_project(可被 stop_project kill)。
⚠ 仍需谨慎的场景:
长循环 / 耗时 > 30s:用 upload+run_project
回调注册(event.on / sensor.on):register 能调用,但 eval 返回时 _result 已定,回调触发的数据拿不回 — 持续监听必须用 upload+run_project
长 session(cloud_control 连云、ESP32 BLE HID 持久会话):建议用工程模式
完整指南见 docs/AGENT_EVAL_GUIDE.md。
代码必须把结果赋给 _result 全局变量。返回值约定:
简单字符串:_result = 'ok'
结构化数据(推荐):_result = json.dumps({'found': True, 'x': 320})
含截图返回:_result = json.dumps({'data': {...}, 'image_base64': '...'}) (MCP 自动识别 image_base64 字段并以图片形式返回给 AI 多模态查看)
image_path 非空时 App 会注入 _im_source 全局变量指向该图片路径; iOS 上若代码中引用 img 变量,会被预读为 cv2 ndarray。
跨平台:iOS 端会自动把 ascript.android. 替换为 ascript.ios.,
并预加载 cv2 / np / Image (PIL) 到执行环境,常用片段几乎无需修改。
完整 API 参见 search_api / get_module_apis(按 platform 选择)。
Inputs: code (required), image_path.
find_colorsB
多点找色:在屏幕上查找符合颜色条件的坐标。 colors 格式:'x,y,#RRGGBB|x,y,#RRGGBB|...',第一个点为锚点,后续为偏移点。 可选带偏差色:'x,y,#RRGGBB-#偏差|...'
Inputs: colors (required), rect, diff.
get_code_exampleB
获取常见自动化任务的可运行代码示例。
Inputs: task (required), platform (required).
get_device_statusA
获取设备完整运行状态(仅 Android)。一次性返回:
device: 品牌/型号/ABI
system: Android 版本/SDK/语言/时区
screen: 分辨率/dpi/方向
battery / network / storage / memory
permissions: 全部权限授权状态
run_mode: 当前运行模式(root / accessibility / screen_only / hid)— 决定可用的 API 集
runtime: 是否正在跑脚本、当前工程名
tools: 已安装工具配置
强烈建议生成脚本前先调用:根据 run_mode 选择 API(如 node.find 仅在 accessibility 模式可用),根据 permissions 决定是否需要先申请权限,根据 runtime.is_script_running 避免互踩。
Inputs: no named parameters.
get_module_apisA
获取指定模块的完整 API 文档,支持模糊匹配。例如 'screen' 可匹配 'ascript.windows.screen'。返回函数签名、参数说明和文档。
Inputs: platform (required), module (required).
get_platform_overviewA
获取指定平台(android/ios/windows)的 API 模块概览,包含模块名、描述、类和函数列表。
Inputs: platform (required).
get_plugin_detailA
获取指定插件的详细文档,包括 API 说明、参数、代码示例和版本历史。 需要先用 list_plugins 查到插件 id。
Inputs: plugin_id (required).
get_project_filesB
获取设备上指定工程的文件树结构。
Inputs: name (required).
get_run_logA
获取设备运行日志(实时收集指定秒数)。 用于查看脚本运行输出、错误信息和 print 内容。 建议在 run_project 后调用,查看脚本是否正常运行或有报错。
Inputs: seconds.
get_setup_guideC
获取指定平台的环境搭建和安装指南。
Inputs: platform (required).
list_pluginsA
查询 AScript 在线插件库,返回所有可用插件列表。 插件提供额外能力:OCR(TomatoOcr)、YOLO 目标检测、HID 硬件控制、AI 大模型、蓝牙通信等。 按下载量排序,包含插件名、作者、描述。
Inputs: no named parameters.
list_projectsA
列出设备上的所有工程。
Inputs: no named parameters.
list_python_packagesA
列出设备 AScript App 内已安装的 Python 第三方库(Android + iOS)。 AI 在写脚本(尤其是 eval_python 片段)前强烈建议先调用,确认要 import 的 lib 在该设备上可用。
Android: 走 /api/status 的 python.packages(importlib.metadata 实时查询)。 iOS: 借 eval_python 跑 importlib.metadata 实时列出。
常见自带库:opencv-python-headless / numpy / pillow / requests / pandas / openpyxl / pymysql / websockets / cryptography 等,具体清单随 App 版本和用户安装的插件而变化,以本工具实时返回为准。
Inputs: no named parameters.
observe_deviceA
一次性获取设备当前状态:截图 + 控件树,比分开调用更快。 返回截图(PNG 图片)和控件树(Android JSON / iOS XML)。 【重要】拿到控件树后,编写代码必须优先使用控件选择器(通过 text/id/className 等属性定位并操作控件),只有控件树中确实找不到目标元素时才用坐标点击。
Inputs: no named parameters.
ocrA
在设备屏幕上执行 OCR 文字识别。返回识别到的文字、位置坐标和置信度。
Inputs: mode, rect, pattern, confidence.
run_projectC
在设备上运行指定工程。
Inputs: name (required).
run_project_debugA
以调试模式启动 Android 工程,让脚本可被 VS Code / Cursor 通过 debugpy attach 调试。 前提:1) 平台为 Android(iOS 不支持);2) 设备必须通过 ADB 连接(USB / adb tcpip)。 行为:自动 adb forward tcp:5678 → 设备 127.0.0.1:5678 + 调用设备 /api/model/run?debug=1,设备端 :py 进程进入 listen+wait_for_client 阻塞,等待 IDE attach。 返回:本地端口、可直接粘贴到 .vscode/launch.json 的 attach 配置片段、操作提示。 用户在 VS Code 按 F5 attach 后,业务从 main 开始运行,断点会被命中。 停止调试请调用 stop_project(同时停止业务和调试器)。
Inputs: name (required).
scan_devicesA
扫描发现所有 AirScript 设备。 同时执行:1) 局域网扫描(WiFi 连接的 Android/iOS 设备)2) ADB 扫描(USB 连接的 Android 设备)。 返回所有发现的设备列表。
Inputs: port.
screen_captureA
截取设备当前屏幕。返回 PNG 图片。用于查看设备当前界面状态。
Inputs: no named parameters.
search_apiA
按关键词搜索 API,覆盖函数名、类名和文档说明。当不确定功能在哪个模块时使用。
Inputs: query (required), platform.
stop_projectA
停止设备上正在运行的工程。
Inputs: no named parameters.
test_selectorA
在设备上实时测试 Selector 选择器,验证是否能精准匹配到目标控件。 传入过滤条件(text/id/type/desc/clickable),返回匹配到的控件及其完整属性。 用于编写代码前验证 node.Selector().text('xxx').find() 等语句是否能定位到正确控件。 条件可组合使用,如同时指定 text 和 clickable。
Inputs: text, id, type, desc, +2 more.
upload_fileC
上传文件到设备上的指定工程。content 为文件内容的 base64 编码。
Inputs: project_name (required), relative_path (required), content_base64 (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Each tool has a clear, distinct purpose. For example, compare_colors checks a specific point, find_colors searches a region, ocr extracts text, and dump_ui_tree vs observe_device differ by output scope. No significant overlap.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., auto_connect, compare_colors, get_device_status). Even 'deploy_and_run' fits the pattern. No mixing of conventions.
With 29 tools, the set is slightly large but well-justified for a broad mobile automation domain covering connection, project lifecycle, UI inspection, code execution, color/OCR, plugins, and more. Could potentially consolidate a few, but still reasonable.
The tool surface covers most essential operations: device connection, project management, UI dump, screenshot, OCR, color ops, code execution, debugging, logs, and plugin listing. Minor gaps like missing a delete_project tool or a disconnect device tool, but overall comprehensive.
Maintenance
Related MCP Connectors
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI assistants to control mobile and desktop devices with natural language, including running automation tasks, taking screenshots, and managing devices.65 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Magic-API development environment, supporting script syntax query, API management, debugging, and knowledge search for efficient development.MIT
- AlicenseBqualityFmaintenanceEnables Android device control via ADB and scrcpy, including device management, app management, file operations, shell commands, input simulation, screen mirroring, and UI element inspection.2531 PyPIApache 2.0
- AlicenseBqualityBmaintenanceEnables AI agents to automate Android and iOS devices, including emulators and physical devices, by capturing screenshots, reading UI accessibility trees, performing touch and text input, and managing app lifecycle and logs.184MIT