HarmonyOS Dev MCP

harmonyos_dev_mcp provides HarmonyOS MCP tools for device discovery, app build and deployment, UI automation, E2E inspection, and log validation.

Links

• PyPI: harmonyos-dev-mcp
• Tool reference: docs/tool_reference.md
• Logs query guide: docs/logs_query.md

What It Provides

The package exposes 18 MCP tools:

Parameter notation:

• name: required
• name?: optional
• name*: conditionally required, depending on the selected mode or target

Device-targeted tools also accept hdc_server? for wireless debugging by IP. Pass the wireless HDC endpoint, for example 192.168.43.34:35215, to route commands as hdc -t 192.168.43.34:35215 .... If both a device SN and an IP endpoint are needed, pass device_id as the SN and hdc_server as the IP endpoint; commands are routed as hdc -t <SN> -s <IP:port> .... You can also set HARMONYOS_HDC_SERVER as a default endpoint.

General tools:

Build tools:

UI tools:

E2E tools:

build_app supports HarmonyOS HAP, HAR, HSP, APP, and HNP build flows. HSP outputs can also be integrated into a HAP with include_hsp=true.

Detailed validation rules, result fields, errors, and examples are in the tool reference.

Layout

mcp_ho_dev/
|- src/harmonyos_dev_mcp/
|  |- build/                   # Hvigor build helpers, signing, packaging, and target handlers
|  |- device/hdc/              # HDC device, package, app, file, and UI adapters
|  |- logs/                    # Log query parsing and history support
|  |- runtime/                 # Server factory and explicit MCP tool registration
|  |- tools/                   # Public MCP tool entrypoints
|  |- ui/                      # UI tree parsing, selectors, actions, and normalization
|  |- utils/                   # Compatibility wrappers
|  `- _common/                 # Shared runtime infrastructure bundled in this package
|- tests/unit/                 # Unit tests grouped by domain
|- docs/                       # Public tool and log query documentation
|- scripts/                    # Release helpers
|- pyproject.toml              # Project metadata and build config
|- uv.lock
|- README.md

Requirements

• Python 3.12+
• DevEco Studio 5.0+
• HarmonyOS SDK toolchains, including hdc
• uv

Install

Install from PyPI:

pip install harmonyos-dev-mcp

Install from source for local development:

uv sync

Run

uv run harmonyos-dev-mcp

Check connected devices:

hdc list targets

Use wireless debugging by IP:

await list_devices(hdc_server="192.168.43.34:35215")
await install_app(r"C:\path\to\app.hap", hdc_server="192.168.43.34:35215")

Or set a default endpoint:

set HARMONYOS_HDC_SERVER=192.168.43.34:35215

Documentation

• Tool Reference
• Logs Query Guide

Build Examples

Build a debug HAP:

await build_app(r"C:\path\to\project", target="hap", build_mode="debug", product="default")

Build HSP modules and integrate them into a HAP:

await build_app(
    r"C:\path\to\project",
    target="hap",
    build_mode="debug",
    product="default",
    include_hsp=True,
    hsp_module_names=["library_one", "library_two"],
)

Build an HNP-injected HAP:

await build_app(r"C:\path\to\project", target="hnp", build_mode="debug", product="default")

Development

Run unit tests:

uv run pytest tests/unit -v

Run with coverage:

uv run pytest tests/unit -v --cov=harmonyos_dev_mcp

Build package artifacts:

uv build --out-dir dist --clear

Notes

• build_app is a long-running tool. Set MCP tools/call timeout to at least 60s, and prefer 120s for cold builds.
• build_app target="hnp" builds a base HAP, injects module HNP packages from entry/hnp, and signs the HAP through SDK packaging tools.
• build_app target="hsp" builds shared modules; build_app target="hap" include_hsp=true can integrate one or more HSP outputs into the HAP.
• logs_query supports errors and markers modes.
• The shared infrastructure that used to live in a separate common package is bundled in harmonyos_dev_mcp._common.

License

Apache License 2.0