JinDaGe - mcp-harmonyos MCP Details

article

README

🚀 MCP HarmonyOS

这是一个用于HarmonyOS开发的模型上下文协议（MCP）服务器。该服务器能让Claude等AI助手与HarmonyOS项目、设备和应用进行交互。

🚀 快速开始

本项目是一个用于HarmonyOS开发的MCP服务器，借助它，AI助手可与HarmonyOS项目、设备及应用交互。使用前需满足一定的前提条件，安装后还需进行相应配置。

✨ 主要特性

设备管理：列出并查询已连接的HarmonyOS设备。
项目信息：读取项目配置、模块和构建输出。
应用管理：列出并检查设备上已安装的应用。
构建验证：检查构建输出和项目结构。

📦 安装指南

全局安装（推荐）

npm install -g mcp-harmonyos

或者使用npx

npx mcp-harmonyos

📚 详细文档

配置

针对OpenCode

添加到 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "harmonyos": {
      "type": "local",
      "command": ["npx", "-y", "mcp-harmonyos"],
      "enabled": true
    }
  }
}

针对Claude Desktop

添加到Claude Desktop配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "harmonyos": {
      "command": "mcp-harmonyos"
    }
  }
}

可用工具

设备管理

`harmonyos_list_devices`

列出所有已连接的HarmonyOS设备。 返回值：包含设备UDID和状态的设备数组。

[
  {
    "udid": "7001005458323933328a01bcf4251a00",
    "status": "connected"
  }
]

`harmonyos_get_device_info`

获取特定设备的详细信息。参数：

deviceId（字符串）：设备UDID。 返回值：设备信息，包括型号、制造商、操作系统版本等。

{
  "udid": "7001005458323933328a01bcf4251a00",
  "model": "HUAWEI Mate 60 Pro",
  "brand": "HUAWEI",
  "manufacturer": "HUAWEI",
  "osVersion": "4.0.0",
  "sdkVersion": "11",
  "buildId": "Mate60Pro 4.0.0.96"
}

项目信息

`harmonyos_get_project_info`

从app.json5获取HarmonyOS项目信息。参数：

projectPath（字符串）：HarmonyOS项目根目录的绝对路径。 返回值：项目元数据，包括包名、版本和模块。

{
  "bundleName": "com.example.myapp",
  "versionCode": 1000000,
  "versionName": "1.0.0",
  "minCompatibleVersionCode": 1000000,
  "targetAPIVersion": 11,
  "modules": ["entry", "library"]
}

`harmonyos_list_modules`

列出项目中的所有模块及其类型（HAP/HSP/HAR）。参数：

projectPath（字符串）：HarmonyOS项目根目录的绝对路径。 返回值：包含模块名称、类型和路径的模块数组。

[
  {
    "name": "entry",
    "type": "HAP",
    "path": "/path/to/project/entry",
    "srcPath": "entry"
  },
  {
    "name": "library",
    "type": "HSP",
    "path": "/path/to/project/library",
    "srcPath": "library"
  }
]

`harmonyos_check_build_outputs`

检查构建输出是否存在并列出它们。参数：

projectPath（字符串）：HarmonyOS项目根目录的绝对路径。 返回值：构建输出信息。

{
  "hasOutputs": true,
  "outputDir": "/path/to/project/outputs",
  "files": ["entry-default-signed.hap", "library-default-signed.hsp"],
  "haps": ["entry-default-signed.hap"],
  "hsps": ["library-default-signed.hsp"]
}

应用管理

`harmonyos_list_installed_apps`

列出设备上所有已安装的应用。参数：

deviceId（字符串）：设备UDID。 返回值：已安装应用的数组。

[
  {
    "bundleName": "com.example.myapp",
    "versionCode": "1000000",
    "versionName": "1.0.0"
  }
]

`harmonyos_get_app_info`

获取已安装应用的详细信息。参数：

deviceId（字符串）：设备UDID。
bundleName（字符串）：应用包名。 返回值：详细的应用信息。

{
  "bundleName": "com.example.myapp",
  "versionCode": "1000000",
  "versionName": "1.0.0",
  "uid": "20010044",
  "installTime": "2026-02-15 10:30:00",
  "updateTime": "2026-02-15 10:30:00",
  "isSystemApp": false,
  "isRemovable": true
}

💻 使用示例

与OpenCode配合使用

配置MCP服务器后，你可以向OpenCode提出如下问题：

"List all connected HarmonyOS devices"
"What's the bundleName of the project in /path/to/my/project?"
"Check if there are build outputs in my project"
"List all installed apps on device 7001005458323933328a01bcf4251a00"
"Show me information about com.example.myapp on my device"

OpenCode将使用MCP工具查询信息，并可结合bash命令进行构建和部署：

"Build the project and deploy to device"
# OpenCode将执行以下操作：
# 1. 使用harmonyos_get_project_info获取包名
# 2. 使用bash命令：hvigorw assembleApp --no-daemon
# 3. 使用harmonyos_check_build_outputs进行验证
# 4. 使用bash命令：hdc file send和bm install进行部署
# 5. 使用bash命令：aa start启动应用

🔧 技术细节

设计理念

此MCP服务器遵循“轻量级查询 + 外部操作”模式：

MCP工具：提供快速、结构化的查询（设备信息、项目元数据、应用状态）。
Bash命令：处理长时间运行的操作（构建、部署）。
AI助手：智能地将两者结合以实现完整的工作流程。这种设计确保：
✅ 快速响应时间（所有查询 < 1 秒）。
✅ 长时间构建无超时问题。
✅ 清晰的错误消息和日志。
✅ 易于维护和扩展。

开发

从源代码构建

git clone <your-repo>
cd mcp-harmonyos
npm install
npm run build
npm start

项目结构

mcp-harmonyos/
├── src/
│   ├── server.ts              # 主要的MCP服务器实现
│   └── types/
│       └── harmonyos-types.ts # TypeScript类型定义
├── build/                      # 编译后的JavaScript输出
├── package.json
├── tsconfig.json
└── README.md

故障排除

"hdc command not found"

确保已安装DevEco Studio，并且hdc在你的PATH中：

# macOS/Linux
export PATH="$PATH:/path/to/deveco-studio/tools"

# Windows
set PATH=%PATH%;C:\path\to\deveco-studio\tools

"No devices connected"

在设备上启用开发者选项（连续点击版本号7次）。
启用USB调试。
通过USB连接设备。
运行hdc list targets验证连接。

"app.json5 not found"

确保提供项目根目录的绝对路径（AppScope/app.json5所在的位置）。

📄 许可证

本项目采用MIT许可证。

贡献

欢迎贡献代码！请随时提交拉取请求。

mcp-harmonyos