harmony-mcp Server

微信小程序 AI 全流程助手，让 AI 直接操控微信开发者工具，零配置开箱即用

GitHub

Documentation

harmony-mcp

npm version npm downloads CI MCP Registry License: MIT Node.js

对 AI 说"帮我发个版本"，然后喝口水，完事了。

小程序开发者的 AI 副驾驶 — 能理解你的项目、诊断编译错误、一键发版的 MCP Server。

不需要云开发，不需要密钥，不需要白名单。装上就能用。

快速开始 · 实际效果 · 工具列表 · 常见问题

为什么选 harmony-mcp？

你的痛点以前怎么做现在怎么做
发版改版本号 → 构建 npm → 上传 → 3 步手动操作对 AI 说"帮我发个版本"
编译报错看日志 → 找文件 → 改代码 → 重新编译对 AI 说"编译报错了帮我修"
包体积超限手动分析 → 猜哪个大 → 试着分包对 AI 说"包超了怎么办"
审核被拒翻文档 → 查隐私 API → 补权限声明对 AI 说"发版前检查合规"
代码质量人肉 review → 凭经验找问题对 AI 说"帮我检查代码质量"

零配置 · 无需密钥 · 无需云开发 · 支持 uni-app / Taro / mpx

🆕 v0.4.2 重大更新

  • 合规检测大幅扩容 — 从 15 条扩展到 32 条审核规则，覆盖隐私弹窗、授权时机、虚拟支付、强制登录、webview 域名、HTTPS 强制等微信审核高频驳回场景
  • 鸿蒙设备操作 — 新增 8 个 HarmonyOS 工具，支持 HAP 安装/卸载/启动/日志/文件传输
  • Linter 14 条规则 — 新增 wx:for 无 key、页面 JS 过大、定时器未清理检测
  • 底层统一 — CliResult 结构化返回 + Tool Annotations 全标注

快速开始

💡 三端（Kiro / Cursor / Claude Desktop）配置内容完全相同，只是文件路径不同。

Kiro

在 .kiro/settings/mcp.json 中添加：

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

Cursor

在 .cursor/mcp.json 中添加：

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

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

全局安装（推荐 Windows 用户）

如果 npx 启动有问题（Windows 常见），改用全局安装：

npm install -g @yujiamei/harmony-mcp

然后把配置中的 "command" 改为 "harmony-mcp"，"args" 改为 []。

就这一步。没有第二步。

前置条件

  1. Node.js >= 18
  2. 微信开发者工具已安装（下载）
  3. 开发者工具「设置 → 安全 → 服务端口」已开启

💡 微信开发者工具安装在默认路径时会自动检测，无需额外配置。

实际效果

一键发版

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

编译诊断 → 自动修复

你：编译报错了帮我修
AI：✗ pages/cart/cart.js:42 - Cannot find module 'utils/pay'
    类型：模块缺失 | 源码：src/pages/cart/cart.tsx
    正在读取文件并修复...
    ✓ 重新编译通过！0 错误
    检测到 2 个运行时隐患：
    - setData 未节流（第 15 行）
    - 调用 wx.getLocation 但未声明权限

包体积分析 + 智能分包

你：包快超了，帮我看看
AI：主包 1.8MB / 2MB ████████░░ 90%
    体积归因：pages/detail 移到分包可省 430KB
    已生成分包方案 + preloadRule 配置
    要我帮你修改 app.json 吗？

核心能力

发版自动化

一句话完成版本递增 + npm 构建 + 上传。发版前自动弹确认框（Elicitation），防止误操作。

编译闭环

报错 → 定位 → 修复 → 重编译，AI 自动循环直到零错误。支持跨框架源码路径映射（Taro→.tsx / uni-app→.vue）。

体积智能

包体积分析 + 体积归因（精确到组件级）+ 智能分包方案 + 分包后体积模拟 + 预加载配置生成。

合规预检

32 条审核规则全量扫描：隐私 API 权限 + 隐私弹窗 + 授权时机 + 虚拟支付 + 强制登录 + webview 域名 + 页面路径 + tabBar 配置 + 诱导分享 + 内容安全 + HTTPS 强制 + 敏感信息硬编码。区分🔴高危必改/🟡建议优化，每条带修复方案。

代码审计

14 条运行时规则扫描 + A/B/C/D 评分 + 视觉报告。setData 性能、异步错误、权限缺失、过期 API、wx:for 无 key、定时器泄漏一网打尽。

与其他方案的区别

harmony-mcpcloudbase-mcpminiprogram-ci
需要云开发❌✅ 必须❌
需要密钥/白名单❌✅✅
AI 可直接调用✅✅❌
能理解项目结构✅❌❌
编译报错自动修复✅❌❌
智能分包 + 归因✅❌❌
合规预检（32 条规则）✅❌❌
代码质量审计（14 条）✅❌❌
跨框架支持✅❌❌
鸿蒙设备操作✅❌❌
零配置使用✅❌❌

harmony-mcp 面向不用云开发的 70% 普通小程序开发者。

完整工具表（28 个）

微信小程序（20 个）

你说的话工具做的事
"帮我发个版本"wechat_publish版本递增 + npm 构建 + 上传
"编译报错了帮我修"wechat_diagnose编译 + 错误解析 + 自动修复循环
"发版前检查合规"wechat_compliance_check32 条审核规则全量扫描
"帮我检查代码质量"wechat_audit14 规则扫描 + 评分
"包超了怎么办"wechat_package_size体积分析 + 进度条报告
"主包超了怎么分包"wechat_subpackage_suggest归因 + 分包方案 + 体积模拟
"帮我看看这个项目"wechat_project_info项目全貌（AppID/页面/配置）
"有哪些页面"wechat_page_list主包 + 分包页面列表
"配置有没有问题"wechat_config_validate校验 project.config + app.json
"依赖有问题吗"wechat_dependency_checknpm 依赖健康检查
"帮我新建一个小程序"wechat_init_project生成项目骨架（3 种模板）
"环境正常吗"wechat_ready_check全链路预检（6 项）
"预览一下"wechat_preview生成预览二维码
"上传 1.2.0 版本"wechat_upload上传代码到微信后台
"构建一下 npm"wechat_build_npm构建 npm 依赖
"帮我登录"wechat_cli_login弹出登录二维码
"打开项目"wechat_open_project在开发者工具中打开
"关闭项目"wechat_close_project关闭当前项目
"重置文件缓存"wechat_reset_fileutils重置文件监听
"检查一下环境"wechat_self_test环境自检

鸿蒙 HarmonyOS（8 个）🆕 Beta

⚠️ 鸿蒙工具已完成开发和单元测试，但尚未在真机环境验证。欢迎有鸿蒙设备的开发者帮忙测试反馈。

你说的话工具做的事
"有哪些鸿蒙设备"harmony_list_devices列出已连接设备/模拟器
"装到设备上"harmony_install安装 HAP 包
"卸载这个应用"harmony_uninstall卸载应用
"在设备上跑起来"harmony_start启动 Ability
"看看设备日志"harmony_log查看 hilog 日志
"把文件传到设备"harmony_file_push推送文件到设备
"把文件拉下来"harmony_file_pull从设备拉取文件
"鸿蒙环境正常吗"harmony_ready_checkHDC + 设备预检

快捷指令（MCP Prompts）

在支持 MCP Prompts 的客户端中输入 / 即可看到：

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

常见问题

连不上？排查清单

症状原因解法
npx 启动报错Windows npx 兼容问题改用全局安装：npm i -g @yujiamei/harmony-mcp，然后 command 改为 harmony-mcp
下载超时公司内网/淘宝镜像npm config set registry https://registry.npmmirror.com 后重试
"找不到微信开发者工具"非默认安装路径项目根目录创建 harmony-mcp.json：{"cliPath": "D:\\你的路径\\cli.bat"}
"需要重新登录"登录态过期对 AI 说"帮我登录"，扫码即可
工具调用无响应服务端口未开启开发者工具 → 设置 → 安全 → 开启服务端口

其他问题

支持 Mac 吗？ 支持。自动检测 macOS 常见安装路径。
支持 uni-app / Taro / mpx 吗？ 支持。传入源码目录会自动识别框架并定位编译产物。产物不存在时会提示先编译。
中文路径有问题吗？ 没有。已在中文路径下充分验证。
能力边界在哪？
  • ✅ 编译层问题（语法错误、模块缺失、配置错误）— 全自动修复
  • ✅ 运行时隐患（setData 性能、异步错误、权限缺失）— 静态扫描检测
  • ⚠️ 运行时逻辑 bug（白屏、接口时序、业务逻辑）— 超出当前能力

更多资源

支持项目

如果 harmony-mcp 帮到了你，给个 ⭐ Star 就是最大的支持！

Star 能让更多小程序开发者发现这个工具，也是我持续维护的动力。

免责声明

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

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

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

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

License

MIT © 朱