Harmonyos

io.github.FadingLight9291117由 GitHub 账号 FadingLight9291117 发布v1.0.3更新于 Oct 24, 2026

MCP server for HarmonyOS development - interact with projects, devices, and applications

已验证STDIO仅桌面文件与存储开发者工具

概览

AI 生成的概览

面向 HarmonyOS 开发的本地 MCP 服务器，让助手查询已连接设备、项目配置、构建产物和已安装应用。

可以做什么
列出已连接的 HarmonyOS 设备，并按设备 ID 读取型号、厂商、系统版本等详情。从 app.json5 读取项目元数据，并列出项目各模块及其 HAP/HSP/HAR 类型。检查构建产物是否存在，并列出生成的 HAP 与 HSP 文件。列出设备上已安装的应用，并查看版本、安装时间、是否为系统应用等详情。
适用场景
适合在开发 HarmonyOS 项目时，让助手无需手动执行 hdc 命令即可查看设备、项目结构、构建产物和已安装应用。README 将其定位为快速只读查询，构建与部署交由 shell 命令完成。
运行要求
需要 Node.js 18 或更高版本，通过 npm 或 npx 在本地安装。需安装 HarmonyOS DevEco Studio，并确保其 hdc 命令行工具在 PATH 中。查询设备和应用时，需通过 USB 连接 HarmonyOS 设备并开启开发者选项和 USB 调试。
安装前请注意
设备和应用查询需要连接设备并开启 USB 调试，这会把设备和已安装应用的信息暴露给助手。项目相关工具需要绝对项目路径。服务器本身只读取信息；构建、部署和启动通过助手可能执行的 shell 命令完成，允许前请先确认这些操作。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Harmonyos，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

MCP HarmonyOS

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

[NPM Version] [GitHub Stars] [License]

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)

bash
npm install -g mcp-harmonyos

Or use with npx

bash
npx mcp-harmonyos

Configuration

For OpenCode

Add to your ~/.config/opencode/opencode.json:

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

json
{  "mcpServers": {    "harmonyos": {      "command": "mcp-harmonyos"    }  }}

Available Tools

Device Management

harmonyos_list_devices

List all connected HarmonyOS devices.

Returns: Array of devices with UDID and status

json
[  {    "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.

json
{  "udid": "7001005458323933328a01bcf4251a00",  "model": "HUAWEI Mate 60 Pro",  "brand": "HUAWEI",  "manufacturer": "HUAWEI",  "osVersion": "4.0.0",  "sdkVersion": "11",  "buildId": "Mate60Pro 4.0.0.96"}

Project Information

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

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

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

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

json
[  {    "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 UDID
  • bundleName (string): The application bundle name

Returns: Detailed application information

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

bash
git clone <your-repo>cd mcp-harmonyosnpm installnpm run buildnpm 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:

bash
# macOS/Linuxexport PATH="$PATH:/path/to/deveco-studio/tools"
# Windowsset PATH=%PATH%;C:\path\to\deveco-studio\tools

"No devices connected"

  1. Enable Developer Options on your device (tap Build Number 7 times)
  2. Enable USB Debugging
  3. Connect device via USB
  4. 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.

Related Resources

来源：README.md，提交 72f0e79

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v1.0.3最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分