MCP HarmonyOS
npm: https://www.npmjs.com/package/mcp-harmonyos
A Model Context Protocol (MCP) server for HarmonyOS development. This server enables AI assistants like Claude to interact with HarmonyOS projects, devices, and applications.
Features
- Device Management: List and query connected HarmonyOS devices
- Project Information: Read project configuration, modules, and build outputs
- Application Management: List and inspect installed applications on devices
- Build Verification: Check build outputs and project structure
Prerequisites
- Node.js 18+
- HarmonyOS DevEco Studio (for hdc command-line tools)
hdc must be available in your PATH
Installation
Global Installation (Recommended)
npm install -g mcp-harmonyos
Or use with npx
Configuration
For OpenCode
Add to your ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"harmonyos": {
"type": "local",
"command": ["npx", "-y", "mcp-harmonyos"],
"enabled": true
}
}
}
For Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"harmonyos": {
"command": "mcp-harmonyos"
}
}
}
Device Management
harmonyos_list_devices
List all connected HarmonyOS devices.
Returns: Array of devices with UDID and status
[
{
"udid": "7001005458323933328a01bcf4251a00",
"status": "connected"
}
]
harmonyos_get_device_info
Get detailed information about a specific device.
Parameters:
deviceId (string): The device UDID
Returns: Device information including model, manufacturer, OS version, etc.
{
"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
Get HarmonyOS project information from app.json5.
Parameters:
projectPath (string): Absolute path to the HarmonyOS project root
Returns: Project metadata including bundleName, version, and modules
{
"bundleName": "com.example.myapp",
"versionCode": 1000000,
"versionName": "1.0.0",
"minCompatibleVersionCode": 1000000,
"targetAPIVersion": 11,
"modules": ["entry", "library"]
}
harmonyos_list_modules
List all modules in a project with their types (HAP/HSP/HAR).
Parameters:
projectPath (string): Absolute path to the HarmonyOS project root
Returns: Array of modules with name, type, and path
[
{
"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
Check if build outputs exist and list them.
Parameters:
projectPath (string): Absolute path to the HarmonyOS project root
Returns: Build output information
{
"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"]
}
Application Management
harmonyos_list_installed_apps
List all installed applications on a device.
Parameters:
deviceId (string): The device UDID
Returns: Array of installed applications
[
{
"bundleName": "com.example.myapp",
"versionCode": "1000000",
"versionName": "1.0.0"
}
]
harmonyos_get_app_info
Get detailed information about an installed application.
Parameters:
deviceId (string): The device UDIDbundleName (string): The application bundle name
Returns: Detailed application information
{
"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
}
Usage Examples
With OpenCode
After configuring the MCP server, you can ask OpenCode questions like:
"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 will use the MCP tools to query information and can combine them with bash commands for building and deploying:
"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
Design Philosophy
This MCP server follows the "lightweight query + external operations" pattern:
- MCP tools provide fast, structured queries (device info, project metadata, app status)
- Bash commands handle long-running operations (building, deploying)
- AI assistants intelligently combine both for complete workflows
This design ensures:
- ✅ Fast response times (all queries < 1 second)
- ✅ No timeout issues with long builds
- ✅ Clear error messages and logs
- ✅ Easy to maintain and extend
Development
Build from Source
git clone <your-repo>
cd mcp-harmonyos
npm install
npm run build
npm start
Project Structure
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
Troubleshooting
"hdc command not found"
Make sure DevEco Studio is installed and hdc is in your PATH:
export PATH="$PATH:/path/to/deveco-studio/tools"
set PATH=%PATH%;C:\path\to\deveco-studio\tools
"No devices connected"
- Enable Developer Options on your device (tap Build Number 7 times)
- Enable USB Debugging
- Connect device via USB
- Run
hdc list targets to verify connection
"app.json5 not found"
Make sure you provide the absolute path to the project root directory (where AppScope/app.json5 is located).
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.