Skip to main content
Glama
ascript-mcp
by ascript-cn

ascript-mcp

Chinese | English

PyPI License: MIT Python

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-mcp

Configuring 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_overview

Get platform API module overview

get_module_apis

Get detailed module API documentation

search_api

Search for APIs by keyword

get_code_example

Get code examples

get_setup_guide

Get environment setup guide

Online Plugins (2)

Tool

Description

list_plugins

Query plugin library list

get_plugin_detail

Get detailed plugin documentation

Device Connection (5)

Tool

Description

auto_connect

Automatically connect to devices from project configuration

scan_devices

Scan LAN + ADB devices

connect_device

Manually connect to a specified device

get_device_status

Get full device running status (running mode/permissions/screen/battery/memory/running scripts, etc., Android only)

list_python_packages

List third-party Python libraries installed on the AScript App (Android + iOS)

Observation Interface (6)

Tool

Description

screen_capture

Capture device screen

dump_ui_tree

Get UI control tree

test_selector

Test if a selector matches

ocr

Screen text recognition

find_colors

Multi-point color search

compare_colors

Multi-point color comparison

Development & Deployment (7)

Tool

Description

create_project

Create a project on the device

upload_file

Upload files to the device (automatically creates project)

run_project

Run project

run_project_debug

Debug mode run (Android + ADB), automatically forwards port 5678 and returns VS Code attach configuration

stop_project

Stop project

get_run_log

Get running logs

eval_python

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 ascript.android.* → ascript.ios.* and preloads cv2/np/Image. See AGENT_EVAL_GUIDE for details

File Management (2)

Tool

Description

list_projects

List projects on the device

get_project_files

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 8000

License

MIT License, see LICENSE for details. Copyright © 2026 Beijing Aoyue Technology Co., Ltd.

More Information

Available Tools

29 tools
auto_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

    A3.8/5.0

    Scored across 29 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to control mobile and desktop devices with natural language, including running automation tasks, taking screenshots, and managing devices.
      6
      5 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Magic-API development environment, supporting script syntax query, API management, debugging, and knowledge search for efficient development.
      MIT
    • A
      license
      B
      quality
      F
      maintenance
      Enables Android device control via ADB and scrcpy, including device management, app management, file operations, shell commands, input simulation, screen mirroring, and UI element inspection.
      25
      31 PyPI
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      18
      4
      MIT