Hypium MCP

Hypium Model Context Protocol (MCP) 服务器，为 HarmonyOS 设备自动化提供强大的工具集。

功能特性

• 🚀 丰富的设备操作工具：支持点击、滑动、文本输入、手势操作等
• 📱 应用管理：应用安装、卸载、启动、停止、信息查询
• 🔍 屏幕观察：屏幕截图、布局分析、元素查找
• 🖱️ 鼠标操作：鼠标点击、移动、滚动等
• 🎯 系统手势：返回、主页、通知中心、控制中心
• 🔧 插件支持：数据采集、报告生成等插件功能
• 🌐 多种启动模式：支持 stdio 和 streamable-http 模式
• ⚙️ 灵活配置：支持环境变量和配置文件

安装

环境要求

• Python >= 3.10
• HarmonyOS 设备（已连接并配置 hdc）
• hdc 工具已安装并配置到 PATH

使用 pip 安装

pip install hypium-mcp

快速开始

1. 启动 MCP 服务器

使用 stdio 模式

python -m hypium_mcp --service-mode stdio

使用 HTTP 模式

python -m hypium_mcp --service-mode streamable-http --port 8000

指定设备

python -m hypium_mcp --device-id <device_serial_number>

2. 在 Claude Desktop 中配置

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "hypium": {
      "command": "python",
      "args": ["-m", "hypium_mcp"],
      "env": {
        "HYPIUM_MCP_DEVICE_ID": "<device_serial_number>"
      }
    }
  }
}

3. 列出可用工具

python -m hypium_mcp list

配置

环境变量

变量名	说明	默认值
HYPIUM_MCP_SERVER_NAME	MCP 服务器名称	HypiumMCP
HYPIUM_MCP_SERVICE_MODE	服务模式	streamable-http
HYPIUM_MCP_HOST	HTTP 服务器地址	localhost
HYPIUM_MCP_PORT	HTTP 服务器端口（http: 8000, streamable-http: 8001, socket: 8002）	8001
HYPIUM_MCP_DEVICE_ID	设备序列号	default
HYPIUM_MCP_HDC_HOST	HDC 服务器地址	127.0.0.1
HYPIUM_MCP_HDC_PORT	HDC 服务器端口	8710
HYPIUM_MCP_HDC_PATH	HDC 可执行文件路径	""
HYPIUM_MCP_WORKING_DIR	工作目录	""
HYPIUM_MCP_OUTPUT_DIR	输出目录	./reports/hypium_mcp_*
HYPIUM_MCP_LOG_LEVEL	日志级别	INFO
HYPIUM_MCP_LOG_FILE	日志文件路径	None
HYPIUM_MCP_LOG_CONSOLE_ENABLE	是否启用控制台日志输出	True
HYPIUM_MCP_LOG_FILE_ENABLE	是否启用日志文件输出	True
HYPIUM_MCP_LOG_MAX_SIZE	单个日志文件最大字节数	5242880（5MB）
HYPIUM_MCP_LOG_MAX_NUM	日志文件最大保留数量	20
HYPIUM_MCP_TIMEOUT	设备连接超时时间（秒）	30
HYPIUM_MCP_EXCLUDE_MODULE	全局排除的模块列表（逗号分隔）	""
HYPIUM_MCP_INCLUDE_MODULE	全局包含的模块列表（逗号分隔）	""
HYPIUM_MCP_EXCLUDE_TOOLS	全局排除的工具列表（逗号分隔）	""
HYPIUM_MCP_INCLUDE_TOOLS	全局包含的工具列表（逗号分隔）	""
HYPIUM_MCP_COORDINATE_VALUE_MODE	坐标值模式（relative_1000/relative_1/absolute）	relative_1000
HYPIUM_MCP_COORDINATE_FORMAT	坐标参数格式（combine: pos=(x,y)，split: x, y 分离）	combine
HYPIUM_MCP_MODE	工具模式	phone
HYPIUM_MCP_TOOLS_MODE_FILE	工具模式配置文件路径	自动查找
HYPIUM_MCP_TOOLS_MODE_JSON	工具模式 JSON 配置（直接传入）	None
HYPIUM_MCP_ADD_LOG_PARAM	是否给工具添加日志参数，支持模型把工具调用的意图输出到工具参数中，便于生成步骤报告	True
HYPIUM_MCP_COLLECT_ENABLE	是否启用数据采集功能	False
HYPIUM_MCP_APP_CONFIG	应用名称映射配置文件路径	自动查找

工具模式配置

通过设置 HYPIUM_MCP_MODE 环境变量来指定工具模式，过滤或者保留不部分工具。

内置模式：

模式名称	说明
default	显示所有支持的工具（无过滤）
device_only	仅设备管理工具
no_gesture	排除手势工具
phone	手机操作模式（默认模式）
pc	PC 操作模式

配置说明：

• 默认模式为 phone，可通过设置 HYPIUM_MCP_MODE=default 显示所有工具
• 配置文件搜索顺序（优先级从高到低）：
  1. 环境变量 HYPIUM_MCP_TOOLS_MODE_FILE 指定的文件路径
  2. 当前工作目录下的 hypium_mcp_tools_config.json
  3. 包内默认配置文件 hypium_mcp/config/hypium_mcp_tools_config.json

模块名称参考：参考下方「支持的工具」小节，每个工具小节标题后括号内即为模块名称。

配置格式：

{
  "模式名称": {
    "include_module": ["模块名1", "模块名2"],
    "exclude_module": ["模块名1", "模块名2"],
    "include_tools": ["工具名1", "工具名2"],
    "exclude_tools": ["工具名1", "工具名2"]
  }
}

自定义配置示例：

在当前工作目录创建 hypium_mcp_tools_config.json：

{
  "custom_mode": {
    "include_module": ["basic", "screen", "observation"],
    "exclude_tools": ["press_key", "clear_app_data"]
  }
}

然后设置环境变量使用自定义模式：

export HYPIUM_MCP_MODE=custom_mode
python -m hypium_mcp

或者通过环境变量指定配置文件路径：

export HYPIUM_MCP_TOOLS_MODE_FILE=/path/to/custom_config.json
export HYPIUM_MCP_MODE=custom_mode
python -m hypium_mcp

应用名称映射配置

支持通过配置文件映射应用显示名称和包名，便于使用中文名称启动应用。

配置文件搜索路径：

1. ~/.hypium_mcp/app_config.json（用户目录）
2. ./app_config.json（当前工作目录）

配置格式：

{
  "bundle_names": {
    "设置": "com.huawei.hmos.settings"
  },
  "main_abilities": {
    "com.huawei.hmos.settings": "com.huawei.hmos.settings.MainAbility"
  }
}

配置后可使用显示名称启动应用：

start_app("设置")  // 等同于 start_app("com.huawei.hmos.settings")

内置支持超过 225 个常用应用的名称映射。

坐标说明

所有传入坐标的工具均使用 0~1000 的归一化坐标，屏幕左上角为 (0, 0)，右下角为 (1000, 1000)。

坐标值会根据实际屏幕分辨率自动映射，无需关心设备的具体像素尺寸。例如：

• (500, 500) — 屏幕中心
• (0, 0) — 屏幕左上角
• (1000, 1000) — 屏幕右下角
• (250, 500) — 屏幕水平方向 1/4 处、垂直方向居中

传入坐标的工具列表

基础操作工具 (basic)

工具名	坐标参数	说明
click	pos	在指定坐标执行点击操作
long_click	pos	在指定坐标执行长按操作
double_click	pos	在指定坐标执行双击操作
swipe	start, end	从起点坐标滑动到终点坐标
drag	start, end	从起点坐标拖拽到终点坐标

鼠标工具 (mouse)

工具名	坐标参数	说明
mouse_click	pos	鼠标点击
mouse_double_click	pos	鼠标双击
mouse_long_click	pos	鼠标长按
mouse_move_to	pos	鼠标移动到指定坐标
mouse_move	start, end	鼠标从起点移动到终点
mouse_drag	start, end	鼠标从起点拖拽到终点
mouse_scroll	pos	在指定坐标处鼠标滚动

通用手势工具 (general_gesture)

工具名	坐标参数	说明
pinch_in	pos（可选）	双指捏合缩小，不传则作用于整个屏幕
pinch_out	pos（可选）	双指捏合放大，不传则作用于整个屏幕
rotate_gesture	pos（可选）	旋转手势，不传则作用于整个屏幕

系统手势工具 (system_gesture)

工具名	坐标参数	说明
drag_to_xiaoyi	pos	拖拽指定坐标处的元素到小艺助手

支持的工具

设备管理工具 (device_manager)

工具名	说明
list_devices	列出所有已连接的设备
get_current_device	获取当前使用的设备信息
connect_device	连接到指定设备
release_device	释放指定设备

基础操作工具 (basic)

工具名	说明
click	在指定坐标执行点击操作
long_click	在指定坐标执行长按操作
double_click	在指定坐标执行双击操作
swipe	从起点滑动到终点
drag	拖拽操作
go_back	返回操作
go_home	返回主页
wait	等待指定时间
press_key	按下指定按键
input_text	输入文本
clear_text	清除文本
start_app	启动应用程序
stop_app	停止应用程序
clear_recent_task	清除最近任务

屏幕工具 (screen)

工具名	说明
screen_off	关闭屏幕
screen_on	打开屏幕
unlock_screen	解锁屏幕
rotate_screen	旋转屏幕

观察工具 (observation)

工具名	说明
screenshot	获取屏幕截图
layout	获取屏幕布局信息
find_elements	查找满足条件的 UI 元素

系统手势工具 (system_gesture)

工具名	说明
open_control_center	打开控制中心
open_notification_center	打开通知中心
drag_to_xiaoyi	拖拽到小艺助手
enter_recent_task	进入最近任务

通用手势工具 (general_gesture)

工具名	说明
pinch_in	双指捏合缩小
pinch_out	双指捏合放大
rotate_gesture	旋转手势

鼠标工具 (mouse)

工具名	说明
mouse_click	鼠标点击
mouse_double_click	鼠标双击
mouse_long_click	鼠标长按
mouse_move_to	鼠标移动到指定位置
mouse_move	鼠标移动
mouse_drag	鼠标拖拽
mouse_scroll	鼠标滚动

应用管理工具 (app_manager)

工具名	说明
get_current_app	获取当前运行的应用
has_app	检查应用是否已安装
stop_all_app	停止所有应用
clear_app_data	清除应用数据
install_app	安装应用
uninstall_app	卸载应用

Toast 工具 (toast)

工具名	说明
start_listen_toast	开始监听 Toast 消息
get_toast	获取 Toast 消息

插件工具 (plugins)

工具名	说明
start_data_collect	开始数据采集
stop_data_collect	停止数据采集
generate_report	生成报告

键盘工具 (keyboard)

工具名	说明
press_shortcut	按下组合快捷键（如 ctrl+c、ctrl+shift+z、alt+tab）

应用管理扩展工具 (app_manager_ext)

工具名	说明
start_app_by_deep_link	通过 Deep Link 启动应用

MCP 管理工具 (mcp_manager)

工具名	说明
mcp_clean_up	清理 MCP 会话资源