harmony-mcp
微信小程序与 HarmonyOS 设备自动化 MCP Server。让 Kiro、Cursor、Claude Desktop 等 AI 客户端直接执行本地开发者工具能力：编译诊断、合规预检、包体积分析、一键上传和鸿蒙设备操作。
当前 npm 稳定版：v0.5.0，共 36 个工具。
不需要云开发，不需要小程序 CI 密钥，不需要 IP 白名单。默认通过微信开发者工具官方 CLI 工作。
Quick Start · 核心能力 · 工具列表 · 配置 · FAQ
Quick Start
前置条件
- Node.js
>= 20 - 已安装微信开发者工具：下载地址
- 微信开发者工具中已开启「设置 -> 安全 -> 服务端口」
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 调用能力，不是微信官方产品。
相关文档
Disclaimer
本项目非微信官方产品，与腾讯公司无任何关联。
harmony-mcp 通过调用微信开发者工具官方公开的 CLI 命令行接口实现微信小程序相关能力，不涉及逆向工程、协议破解或非公开接口调用。使用本工具前，请确保你已阅读并同意《微信小程序平台服务条款》。
"微信"及"小程序"为腾讯公司的注册商标，本项目中的使用仅用于描述兼容性，不构成任何官方背书。
本软件按"原样"提供，不附带任何明示或暗示的担保。作者不对因使用本软件导致的任何直接或间接损失承担责任。详见 LICENSE。
License
MIT © 朱