harmony-mcp

微信小程序与 HarmonyOS 设备自动化 MCP Server。让 Kiro、Cursor、Claude Desktop 等 AI 客户端直接执行本地开发者工具能力：编译诊断、合规预检、包体积分析、一键上传和鸿蒙设备操作。

当前 npm 稳定版：v0.5.0，共 36 个工具。

不需要云开发，不需要小程序 CI 密钥，不需要 IP 白名单。默认通过微信开发者工具官方 CLI 工作。

Quick Start · 核心能力 · 工具列表 · 配置 · FAQ

---

Quick Start

前置条件

1. Node.js >= 20
2. 已安装微信开发者工具：下载地址
3. 微信开发者工具中已开启「设置 -> 安全 -> 服务端口」

Kiro / Cursor / Claude Desktop

三类客户端配置内容相同，只是配置文件路径不同。

{
  "mcpServers": {
    "harmony-mcp": {
      "command": "npx",
      "args": ["-y", "@yujiamei/harmony-mcp"]
    }
  }
}

常见配置路径：

客户端	配置文件
Kiro	.kiro/settings/mcp.json
Cursor	.cursor/mcp.json
Claude Desktop macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop Windows	%APPDATA%\Claude\claude_desktop_config.json

Windows 如果 npx 启动不稳定，可以改用全局安装：

npm install -g @yujiamei/harmony-mcp

然后将配置改为：

{
  "mcpServers": {
    "harmony-mcp": {
      "command": "harmony-mcp",
      "args": []
    }
  }
}

---

核心能力

场景	你可以对 AI 说	做什么
一键发版	"帮我发个版本，描述是修复购物车 bug"	读取版本、构建 npm、上传代码
编译诊断	"编译报错了，帮我定位"	调用开发者工具编译，解析错误并给出修复建议
包体积分析	"主包快超了，帮我看看"	分析包体积、定位大文件、给出分包建议
合规预检	"发版前检查一下合规"	扫描 32 条审核高频规则
代码审计	"帮我检查代码质量"	扫描 14 条运行时规则并评分
鸿蒙设备	"把这个 HAP 装到设备上"	通过 HDC 安装、启动、看日志、传文件

一键发版

你：帮我发个版本，描述是修复了购物车 bug
AI：读取项目信息... OK
    构建 npm... OK
    上传代码 v1.2.4... OK
    发版完成。去微信后台提交审核即可。

编译诊断

你：编译报错了，帮我定位
AI：pages/cart/cart.js:42 Cannot find module 'utils/pay'
    类型：模块缺失
    源码：src/pages/cart/cart.tsx
    建议：检查 import 路径或补齐对应模块

合规预检

wechat_compliance_check 覆盖隐私弹窗、授权时机、虚拟支付、强制登录、web-view 域名、HTTPS、页面路径、tabBar、诱导分享、内容安全和敏感信息硬编码等高频审核问题。

---

工具列表

v0.5.0 稳定版共 36 个工具：

分类	数量	代表工具
微信基础操作	10	wechat_preview、wechat_auto_preview、wechat_cache_clean
微信项目分析	4	wechat_project_info、wechat_package_size、wechat_subpackage_suggest
微信项目检查	4	wechat_config_validate、wechat_audit、wechat_compliance_check
微信智能流程	2	wechat_diagnose、wechat_publish
微信 CI / 环境 / 运行时	8	wechat_ci_preview、wechat_ready_check、wechat_runtime_diagnose
HarmonyOS 设备操作	8	harmony_list_devices、harmony_install、harmony_log

完整工具表见 docs/TOOLS.md。

---

配置

默认情况下无需配置。只有在微信开发者工具或 HDC 不在常见路径时，才需要在运行目录创建 harmony-mcp.json。

{
  "cliPath": "D:\\Program Files\\Tencent\\微信web开发者工具\\cli.bat",
  "hdcPath": "D:\\Huawei\\Sdk\\openharmony\\toolchains\\hdc.exe",
  "appJsonPath": "src/app.json"
}

也可以通过环境变量指定微信开发者工具 CLI：

WECHAT_DEVTOOLS_CLI="D:\\Program Files\\Tencent\\微信web开发者工具\\cli.bat"

---

Roadmap

下一阶段继续补强：

能力	状态
HarmonyOS 真机验证矩阵	计划中
uni-app / Taro 源码映射增强	计划中
运行时诊断 Beta 稳定化	持续迭代
工具清单自动校验	计划中

---

MCP Prompts

在支持 MCP Prompts 的客户端中输入 /，可以看到 4 个快捷指令：

指令	功能
/harmony-check	一键环境预检
/harmony-audit	全量代码审计与评分报告
/harmony-shrink	包体积分析与分包建议
/harmony-publish	合规预检、编译诊断、确认发版

更多示例见 docs/PROMPTS.md。

---

FAQ

连不上怎么办？

症状	常见原因	处理方式
npx 启动报错	Windows 环境兼容问题	改用全局安装：npm i -g @yujiamei/harmony-mcp
下载超时	网络或 npm registry 问题	执行 npm config set registry https://registry.npmmirror.com 后重试
找不到微信开发者工具	安装路径非默认	配置 WECHAT_DEVTOOLS_CLI 或 harmony-mcp.json.cliPath
需要重新登录	微信开发者工具登录态过期	对 AI 说"帮我登录"，扫码确认
工具调用无响应	服务端口未开启	微信开发者工具 -> 设置 -> 安全 -> 开启服务端口

支持跨端框架吗？

支持 uni-app、Taro、MPX 的基础识别与编译产物定位。当前稳定版已支持自动定位产物目录；更精确的源码映射增强正在 main 分支开发中。

会上传代码或修改文件吗？

只有调用上传、构建、初始化项目、鸿蒙安装等明确操作时才会产生外部动作。只读分析类工具会通过 MCP Tool Annotations 标注为只读，方便客户端做安全提示。

这是微信官方工具吗？

不是。本项目通过微信开发者工具官方公开 CLI 调用能力，不是微信官方产品。

---

相关文档

• 完整工具表
• Prompt 指令库
• 贡献指南
• 安全政策

---

Disclaimer

本项目非微信官方产品，与腾讯公司无任何关联。

harmony-mcp 通过调用微信开发者工具官方公开的 CLI 命令行接口实现微信小程序相关能力，不涉及逆向工程、协议破解或非公开接口调用。使用本工具前，请确保你已阅读并同意《微信小程序平台服务条款》。

"微信"及"小程序"为腾讯公司的注册商标，本项目中的使用仅用于描述兼容性，不构成任何官方背书。

本软件按"原样"提供，不附带任何明示或暗示的担保。作者不对因使用本软件导致的任何直接或间接损失承担责任。详见 LICENSE。

---

License

MIT © 朱