harmonyos

MCP HarmonyOS

npm: https://www.npmjs.com/package/mcp-harmonyos

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

功能特性

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

先决条件

• Node.js 18+
• HarmonyOS DevEco Studio（用于 hdc 命令行工具）
• hdc 必须在 PATH 中可用

安装

全局安装（推荐）

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（string）：设备 UDID

返回：设备信息，包括型号、制造商、OS 版本等

{
  "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（string）：HarmonyOS 项目根目录的绝对路径

返回：项目元数据，包括 bundleName、版本和模块

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

harmonyos_list_modules

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

参数：

• projectPath（string）：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（string）：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（string）：设备 UDID

返回：已安装应用的数组

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

harmonyos_get_app_info

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

参数：

• deviceId（string）：设备 UDID
• bundleName（string）：应用的 bundle 名称

返回：应用详细信息

{
  "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 will:
# 1. Use harmonyos_get_project_info to get bundleName
# 2. Use bash: hvigorw assembleApp --no-daemon
# 3. Use harmonyos_check_build_outputs to verify
# 4. Use bash: hdc file send and bm install to deploy
# 5. Use bash: aa start to launch the app

设计理念

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

• MCP 工具提供快速、结构化的查询（设备信息、项目元数据、应用状态）
• Bash 命令处理耗时较长的操作（构建、部署）
• AI 助手智能地结合两者，完成完整工作流

此设计可确保：

• ✅ 响应速度快（所有查询均 < 1 秒）
• ✅ 长时间构建不会出现超时问题
• ✅ 错误消息和日志清晰
• ✅ 易于维护和扩展

开发

从源代码构建

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

项目结构

mcp-harmonyos/
├── src/
│   ├── server.ts              # Main MCP server implementation
│   └── types/
│       └── harmonyos-types.ts # TypeScript type definitions
├── build/                      # Compiled JavaScript output
├── 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”

1. 在设备上启用开发者选项（点击版本号 7 次）
2. 启用 USB 调试
3. 使用 USB 连接设备
4. 运行 hdc list targets 以验证连接

“app.json5 not found”

请确保提供项目根目录的绝对路径（该目录中包含 AppScope/app.json5）。

许可证

MIT

参与贡献

欢迎贡献！请随时提交 Pull Request。

相关资源

• Model Context Protocol
• HarmonyOS 文档
• OpenCode