使用说明

项目简介

HarmonyOS MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为 LLM 应用提供控制 HarmonyOS 设备的上下文服务。通过此服务器，LLM 可以调用预定义的工具来管理应用、操作 UI 界面、控制媒体等，从而实现与 HarmonyOS 设备的交互。

主要功能点

应用管理：
- 列出设备上已安装的应用
- 启动指定的应用
- 停止指定的应用
- 获取当前正在运行的应用
UI 操作：
- 获取当前屏幕的UI布局信息，包括可点击元素
- 模拟点击屏幕坐标
- 模拟长按屏幕坐标
- 模拟屏幕滑动
- 在指定坐标输入文本
媒体控制：
- 截取设备屏幕截图
- 控制媒体播放状态（播放/暂停）
- 播放下一首媒体
- 播放上一首媒体
- 增大设备音量
- 减小设备音量
- 静音设备

安装步骤

克隆仓库

git clone https://github.com/XixianLiang/HarmonyOS-mcp-server.git
cd HarmonyOS-mcp-server

设置环境 仓库推荐使用 'uv' 管理 Python 环境。请确保已安装 'uv'。

uv python install 3.13  # 安装 Python 3.13 (如果未安装)
uv sync              # 安装项目依赖

服务器配置

MCP客户端需要配置以下信息以连接到 HarmonyOS MCP Server。以下是 'MCPServerStdio' 类型的服务器配置示例，适用于 'openai-agents SDK' 等 MCP 客户端。

{
  "serverName": "HarmonyOS MCP Server",
  "command": "<path/to/your/uv>",
  "args": [
    "--directory",
    "<path/to/HarmonyOS-mcp-server>",
    "run",
    "server.py"
  ]
}

配置说明:

'serverName': 服务器名称，可以自定义，用于在客户端标识服务器。
'command': 启动服务器的命令。请将 '<path/to/your/uv>' 替换为你本地 'uv' 可执行文件的路径。如果 'uv' 已添加到系统环境变量，则可以直接使用 'uv'。
'args': 启动命令的参数列表。
- '--directory': 指定服务器代码所在的目录。请将 '<path/to/HarmonyOS-mcp-server>' 替换为你克隆仓库的本地路径。
- 'run server.py': 指示 'uv' 运行 'server.py' 文件来启动 MCP 服务器。

注意: 请根据你的实际 'uv' 安装路径和仓库代码存放路径修改 'command' 和 'args' 中的路径信息。

基本使用方法

启动服务器: 根据上述配置，使用 MCP 客户端提供的功能启动 HarmonyOS MCP Server。
客户端连接: 在 MCP 客户端中配置上述服务器信息，建立与 HarmonyOS MCP Server 的连接。
调用工具: 通过 MCP 客户端，可以调用服务器提供的各种工具，例如 'list_app' (列出应用), 'launch_app' (启动应用), 'get_screenshot' (获取截图) 等，从而控制 HarmonyOS 设备。
参考示例: 仓库的 'README.md' 文件中提供了使用 'openai-agents SDK' 连接和调用服务器工具的 Python 代码示例，可以参考学习。

关键词