MCP Harmonyos

🚀 MCP HarmonyOS

このプロジェクトは、HarmonyOS開発用のModel Context Protocol (MCP) サーバーです。このサーバーにより、ClaudeなどのAIアシスタントが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

戻り値: モデル、メーカー、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 (文字列): 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 (文字列): 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に以下のような質問をすることができます。

"接続されているすべてのHarmonyOSデバイスを一覧表示"
"/path/to/my/projectのプロジェクトのbundleNameは何ですか？"
"私のプロジェクトにビルド出力があるかチェック"
"デバイス7001005458323933328a01bcf4251a00にインストールされているすべてのアプリを一覧表示"
"私のデバイス上のcom.example.myappに関する情報を表示"

OpenCodeはMCPツールを使用して情報をクエリし、ビルドやデプロイのためのbashコマンドと組み合わせることができます。

"プロジェクトをビルドしてデバイスにデプロイ"
# OpenCodeは以下のことを行います:
# 1. harmonyos_get_project_infoを使用してbundleNameを取得
# 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