MCP Harmonyos

🚀 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"

1. 在設備上啟用開發者選項（連續點擊版本號7次）。
2. 啟用USB調試。
3. 通過USB連接設備。
4. 運行hdc list targets驗證連接。

"app.json5 not found"

確保提供項目根目錄的絕對路徑（AppScope/app.json5所在的位置）。

📄 許可證

本項目採用MIT許可證。

貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

相關資源

• Model Context Protocol
• HarmonyOS Documentation
• OpenCode