{
  "markdown": "# MCP HarmonyOS\n\n**npm**: https://www.npmjs.com/package/mcp-harmonyos\n\n[![NPM Version](https://img.shields.io/npm/v/mcp-harmonyos)](https://www.npmjs.com/package/mcp-harmonyos)\n[![GitHub Stars](https://img.shields.io/github/stars/FadingLight9291117/mcp-harmonyos)](https://github.com/FadingLight9291117/mcp-harmonyos)\n[![License](https://img.shields.io/npm/l/mcp-harmonyos)](https://github.com/FadingLight9291117/mcp-harmonyos/blob/main/LICENSE)\n\nA Model Context Protocol (MCP) server for HarmonyOS development. This server enables AI assistants like Claude to interact with HarmonyOS projects, devices, and applications.\n\n## Features\n\n- **Device Management**: List and query connected HarmonyOS devices\n- **Project Information**: Read project configuration, modules, and build outputs\n- **Application Management**: List and inspect installed applications on devices\n- **Build Verification**: Check build outputs and project structure\n\n## Prerequisites\n\n- Node.js 18+ \n- HarmonyOS DevEco Studio (for hdc command-line tools)\n- `hdc` must be available in your PATH\n\n## Installation\n\n### Global Installation (Recommended)\n\n```bash\nnpm install -g mcp-harmonyos\n```\n\n### Or use with npx\n\n```bash\nnpx mcp-harmonyos\n```\n\n## Configuration\n\n### For OpenCode\n\nAdd to your `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"harmonyos\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"mcp-harmonyos\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### For Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"harmonyos\": {\n      \"command\": \"mcp-harmonyos\"\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Device Management\n\n#### `harmonyos_list_devices`\nList all connected HarmonyOS devices.\n\n**Returns**: Array of devices with UDID and status\n\n```json\n[\n  {\n    \"udid\": \"7001005458323933328a01bcf4251a00\",\n    \"status\": \"connected\"\n  }\n]\n```\n\n#### `harmonyos_get_device_info`\nGet detailed information about a specific device.\n\n**Parameters**:\n- `deviceId` (string): The device UDID\n\n**Returns**: Device information including model, manufacturer, OS version, etc.\n\n```json\n{\n  \"udid\": \"7001005458323933328a01bcf4251a00\",\n  \"model\": \"HUAWEI Mate 60 Pro\",\n  \"brand\": \"HUAWEI\",\n  \"manufacturer\": \"HUAWEI\",\n  \"osVersion\": \"4.0.0\",\n  \"sdkVersion\": \"11\",\n  \"buildId\": \"Mate60Pro 4.0.0.96\"\n}\n```\n\n### Project Information\n\n#### `harmonyos_get_project_info`\nGet HarmonyOS project information from app.json5.\n\n**Parameters**:\n- `projectPath` (string): Absolute path to the HarmonyOS project root\n\n**Returns**: Project metadata including bundleName, version, and modules\n\n```json\n{\n  \"bundleName\": \"com.example.myapp\",\n  \"versionCode\": 1000000,\n  \"versionName\": \"1.0.0\",\n  \"minCompatibleVersionCode\": 1000000,\n  \"targetAPIVersion\": 11,\n  \"modules\": [\"entry\", \"library\"]\n}\n```\n\n#### `harmonyos_list_modules`\nList all modules in a project with their types (HAP/HSP/HAR).\n\n**Parameters**:\n- `projectPath` (string): Absolute path to the HarmonyOS project root\n\n**Returns**: Array of modules with name, type, and path\n\n```json\n[\n  {\n    \"name\": \"entry\",\n    \"type\": \"HAP\",\n    \"path\": \"/path/to/project/entry\",\n    \"srcPath\": \"entry\"\n  },\n  {\n    \"name\": \"library\",\n    \"type\": \"HSP\",\n    \"path\": \"/path/to/project/library\",\n    \"srcPath\": \"library\"\n  }\n]\n```\n\n#### `harmonyos_check_build_outputs`\nCheck if build outputs exist and list them.\n\n**Parameters**:\n- `projectPath` (string): Absolute path to the HarmonyOS project root\n\n**Returns**: Build output information\n\n```json\n{\n  \"hasOutputs\": true,\n  \"outputDir\": \"/path/to/project/outputs\",\n  \"files\": [\"entry-default-signed.hap\", \"library-default-signed.hsp\"],\n  \"haps\": [\"entry-default-signed.hap\"],\n  \"hsps\": [\"library-default-signed.hsp\"]\n}\n```\n\n### Application Management\n\n#### `harmonyos_list_installed_apps`\nList all installed applications on a device.\n\n**Parameters**:\n- `deviceId` (string): The device UDID\n\n**Returns**: Array of installed applications\n\n```json\n[\n  {\n    \"bundleName\": \"com.example.myapp\",\n    \"versionCode\": \"1000000\",\n    \"versionName\": \"1.0.0\"\n  }\n]\n```\n\n#### `harmonyos_get_app_info`\nGet detailed information about an installed application.\n\n**Parameters**:\n- `deviceId` (string): The device UDID\n- `bundleName` (string): The application bundle name\n\n**Returns**: Detailed application information\n\n```json\n{\n  \"bundleName\": \"com.example.myapp\",\n  \"versionCode\": \"1000000\",\n  \"versionName\": \"1.0.0\",\n  \"uid\": \"20010044\",\n  \"installTime\": \"2026-02-15 10:30:00\",\n  \"updateTime\": \"2026-02-15 10:30:00\",\n  \"isSystemApp\": false,\n  \"isRemovable\": true\n}\n```\n\n## Usage Examples\n\n### With OpenCode\n\nAfter configuring the MCP server, you can ask OpenCode questions like:\n\n```\n\"List all connected HarmonyOS devices\"\n\"What's the bundleName of the project in /path/to/my/project?\"\n\"Check if there are build outputs in my project\"\n\"List all installed apps on device 7001005458323933328a01bcf4251a00\"\n\"Show me information about com.example.myapp on my device\"\n```\n\nOpenCode will use the MCP tools to query information and can combine them with bash commands for building and deploying:\n\n```\n\"Build the project and deploy to device\"\n# OpenCode will:\n# 1. Use harmonyos_get_project_info to get bundleName\n# 2. Use bash: hvigorw assembleApp --no-daemon\n# 3. Use harmonyos_check_build_outputs to verify\n# 4. Use bash: hdc file send and bm install to deploy\n# 5. Use bash: aa start to launch the app\n```\n\n## Design Philosophy\n\nThis MCP server follows the \"lightweight query + external operations\" pattern:\n\n- **MCP tools** provide fast, structured queries (device info, project metadata, app status)\n- **Bash commands** handle long-running operations (building, deploying)\n- **AI assistants** intelligently combine both for complete workflows\n\nThis design ensures:\n- ✅ Fast response times (all queries < 1 second)\n- ✅ No timeout issues with long builds\n- ✅ Clear error messages and logs\n- ✅ Easy to maintain and extend\n\n## Development\n\n### Build from Source\n\n```bash\ngit clone <your-repo>\ncd mcp-harmonyos\nnpm install\nnpm run build\nnpm start\n```\n\n### Project Structure\n\n```\nmcp-harmonyos/\n├── src/\n│   ├── server.ts              # Main MCP server implementation\n│   └── types/\n│       └── harmonyos-types.ts # TypeScript type definitions\n├── build/                      # Compiled JavaScript output\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n## Troubleshooting\n\n### \"hdc command not found\"\n\nMake sure DevEco Studio is installed and `hdc` is in your PATH:\n\n```bash\n# macOS/Linux\nexport PATH=\"$PATH:/path/to/deveco-studio/tools\"\n\n# Windows\nset PATH=%PATH%;C:\\path\\to\\deveco-studio\\tools\n```\n\n### \"No devices connected\"\n\n1. Enable Developer Options on your device (tap Build Number 7 times)\n2. Enable USB Debugging\n3. Connect device via USB\n4. Run `hdc list targets` to verify connection\n\n### \"app.json5 not found\"\n\nMake sure you provide the absolute path to the project root directory (where `AppScope/app.json5` is located).\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Related Resources\n\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [HarmonyOS Documentation](https://developer.harmonyos.com/)\n- [OpenCode](https://opencode.ai/)\n",
  "bytes": 7392,
  "sha": "b15fd93c4e4b20ce327617051730c2d057eea303c3c3c8e5a730c69dad21b490",
  "repo_slug": "fadinglight9291117/mcp-harmonyos",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fadinglight9291117_harmonyos_e3dc65a4/readme"
}