harmonyos

MCP HarmonyOS

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

HarmonyOS 開発向けの Model Context Protocol（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）：アプリケーションのバンドル名

戻り値：アプリケーションの詳細情報

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

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

関連リソース

• Model Context Protocol
• HarmonyOS Documentation
• OpenCode