Agent-first MCP server for WeChat Mini Program debugging & automation via WeChat DevTools.
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
Not yet automatically verified
We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.
Manual Client & Custom JSON ConfigExpand JSON ▾
Client Config & Setup
Choose your client or environment
Target File:
💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.
Documentation Overview
weapp-agent-mcp
Agent-first MCP server for WeChat Mini Program debugging, automation, and lightweight regression testing.
面向 agent 的微信小程序 MCP 服务 — 让 Claude Code / Cursor / Codex 等 agent 在对话中直接驱动微信开发者工具完成调试、UI 操作、页面巡检与轻量测试。
📖 Changelog · 🐛 Issues · 💬 Discussions
weapp-agent-mcp 是一个面向 agent 的微信小程序 MCP 服务，基于 miniprogram-automator 封装微信开发者工具自动化能力，用于页面调试、元素操作、轻量回归测试与恢复友好型排查。
它适合：
- agent 主开发 / 主调试
- 串行截图与页面巡检
- 轻量 scenario / report
- 基于稳定 selector 的自动化验证
它当前不应被宣传为：
- 并发截图通道
- 超长高压全链路回归引擎
文档导航
更完整的文档入口见 docs/README.md。
为什么选 weapp-agent-mcp
如果你已经在用 Claude Code / Cursor / Codex 等 agent 写小程序，传统的 miniprogram-automator 脚本式调用不够顺手 — 你得让 agent 写 node 脚本、跑、读输出、再调整。本项目把自动化能力直接暴露成 agent 工具调用，让 agent 在对话中可以：
- 🤖 零脚本调试 — 直接调用
mp_screenshot/page_snapshot/element_tap，不必中转脚本 - 🔁 恢复友好 — 内置
mp_healthCheck/mp_recoverConnection，断连后能自愈，长会话更稳 - 📋 轻量回归 —
mp_runScenario+mp_generateScenarioReport产出 markdown 报告，适合给 PR / oncall 用 - 🎯 稳定 selector 优先 — 设计上鼓励
qa-*命名锚点，减少 UI 改版后的脚本碎裂
适用 / 不适用对比
| 场景 | 是否适用 |
|---|---|
| Agent 主动驱动调试 / 巡检 | ✅ 主推场景 |
| 写传统脚本式 e2e 测试 | ⚪ 直接用原生 miniprogram-automator SDK 更轻 |
| 并发截图 / 压测 | ❌ 不适用 — 截图通道按串行设计 |
| 长会话 / 多轮调试 | ✅ 有 health / recover 工具兜底 |
| CI 上的长链路回归 | ⚠️ 拆短 scenario 后可用，超长链路建议专业框架 |
前置要求
- 已安装微信开发者工具，支持命令行访问（
cli/cli.bat） - 本地已安装 Node.js 18+ 和
npm - 有可以在开发者工具中打开的小程序项目
- 已在微信开发者工具中开启自动化测试与服务端口
快速开始
方式一：通过 npm / npx 接入（推荐，普通用户默认这样用）
不需要先把仓库拉到本地，也不需要自己手动构建 dist。只要本机有 Node.js 和 npx，就可以直接在 MCP 客户端里这样配置：
如果你希望在 Claude 等客户端里用更短的别名，也可以把 MCP server key 命名为
weapp-dev，但发布包名和服务名以weapp-agent-mcp为准。
可选：如果你习惯全局安装，也可以先执行：
然后把 MCP 配置改成：
方式二：本地源码构建接入（仅开发者 / 贡献者）
只有在以下场景才需要这样用：
- 你正在开发这个仓库本身
- 你要调试尚未发布到 npm 的改动
- 你要在本地修改源码后立刻验证
本地开发
重要边界
mp_screenshot当前按串行单通道能力设计，不支持并发压测- 复杂业务链建议拆成多个短 scenario，而不是一个超长 scenario
page_snapshot、mp_screenshot、长mp_runScenario在连续复杂操作后可能超时- 若出现连续失败，先运行
mp_healthCheck；仅当needsRecovery=true时执行mp_recoverConnection - 稳定性高度依赖业务页面提供清晰的
qa-*selector 或其他稳定定位锚点
MCP 客户端集成
Claude Code 自动批准工具权限
由于使用 Claude Code 调用 MCP 工具时，会触发工具调用权限申请，此时可能会丢失 MCP 与微信开发者工具的连接状态，由于获取控制台输出高度依赖连接状态，此时会无法连贯的获取输出日志，所以建议手动添加权限：
在项目目录下创建 .claude/settings.local.json 文件，或在已有文件添加以下内容后即可免确认直接调用工具，或者根据需要添加您允许免确认调用的工具：
注意： 工具名称格式为
mcp__<服务器名称>__<工具名称>，请确保服务器名称与您的 MCP 配置中的名称一致。
可选：人工预启动微信开发者工具
默认流程无需 agent 手动执行 CLI：直接调用 mp_ensureConnection，本地端口未监听且允许 AutoLaunch 时，server 会自行执行 cli auto。下面的命令只用于人工排障，或显式设置 WEAPP_AUTOLAUNCH=false 后由用户自行预启动开发者工具。
💡 在开始之前：
- 打开微信开发者工具
- 进入 设置 → 安全设置 → 服务端口
- 开启 "HTTP 调试" 和 "自动化测试"
人工使用命令行启动
使用命令行启动微信开发者工具并自动开启 WebSocket 服务：
macOS：
Windows：
其中：
--project指定小程序项目目录路径（请替换为实际的项目路径）--auto-port指定 automation websocket 端口（默认 9420）。注意：这个 flag 在cli auto --help输出里看不到，但官方miniprogram-automatorSDK 内部一直用，是有效参数
⚠️ 警告 由于沙箱机制，部分客户端不允许 MCP 访问项目目录以外的微信开发者工具的 cli，所以这里只介绍了使用 WebSocket 服务
环境变量配置
通过环境变量控制自动化工具如何连接到微信开发者工具：
| 变量 | 说明 |
|---|---|
WEAPP_WS_ENDPOINT | 【推荐】 已运行的开发者工具自动化 WebSocket 端点。设置后，服务器使用 connect 模式而不是启动新实例。示例：ws://localhost:9420 |
WECHAT_DEVTOOLS_CLI_PATH | 微信开发者工具 CLI 路径（如果默认路径有效则可选）。 |
WEAPP_AUTOMATOR_MODE | 强制使用 launch 或 connect 模式。除非提供了 WEAPP_WS_ENDPOINT，否则默认为 launch。 |
WEAPP_DEVTOOLS_PORT | launch 模式下传给 cli auto --auto-port 的自动化端口。不会在失败后自动切到其他端口。 |
WEAPP_DEVTOOLS_TIMEOUT | 启动超时时间（毫秒，默认 30000）。 |
WEAPP_AUTO_ACCOUNT | 传递给 --auto-account 用于自动登录。 |
WEAPP_DEVTOOLS_TICKET | 启动时传递给 --ticket。 |
WEAPP_TRUST_PROJECT | 设置为 true 以在启动时包含 --trust-project。 |
WEAPP_DEVTOOLS_ARGS | 启动时的额外 CLI 参数（空格分隔）。 |
WEAPP_DEVTOOLS_CWD | 传递给开发者工具进程的工作目录。 |
WEAPP_AUTOCLOSE | 设置为 true 时，每次工具调用后关闭开发者工具会话。 |
WEAPP_AUTOLAUNCH | 本地 connect 目标端口未监听时是否允许 mp_ensureConnection 使用 cli auto 拉起开发者工具；默认允许，设为 false 禁用。不会自动切换端口或拉起远程目标。 |
WEAPP_LAUNCH_TIMEOUT | 启动超时时间（毫秒，默认 45000） |
WEAPP_CONNECT_TIMEOUT | 连接超时时间（毫秒，默认 45000） |
WEAPP_PROJECT_PATH | 小程序项目路径（可选） |
注意：
launch/ 本地自动拉起最终都需要可解析的小程序项目目录。可通过connection.projectPath、WEAPP_PROJECT_PATH、mp_setDefaultProject的持久化默认值、最近项目或当前工作目录提供；显式设置的默认项目不会被后续活动会话覆盖。
工具调用可以通过 connection 对象覆盖这些默认值中的大部分。
连接模式说明
模式 A：连接已有 IDE（connect）
适用于你已经手动打开微信开发者工具，并且已经在 设置 → 安全设置 → 服务端口 中开启了自动化。
这个模式下：
WEAPP_WS_ENDPOINT必须指向可被miniprogram-automator.connect()连接的 websocket endpoint- 不要把 IDE HTTP 端口误当成 websocket 端口
- 不要手动执行
cli open、cli auto、cli quit - 默认直接调用
mp_ensureConnection；它会优先复用现有会话，并在本地端口未监听时按配置自愈 - 只想只读探测，或 ensure / recovery 已失败时，再调用
mp_diagnoseConnection - 不要自动切端口；如需禁止 ensure 自动执行
cli auto，设置WEAPP_AUTOLAUNCH=false
模式 B：由 MCP 拉起 IDE（launch）
适用于当前未打开 IDE，需要 MCP 通过 CLI 启动项目。
这个模式下：
WEAPP_DEVTOOLS_PORT表示cli auto --auto-port使用的自动化端口- 只有在明确使用
launch模式时，MCP 才应该启动 IDE - 如果检测到同项目已经有 IDE 实例在运行，应停止自动 launch 并返回诊断信息
connect与launch两种模式不要混用
--port 和 --auto-port 的区别
微信开发者工具至少涉及两类端口：
--port：IDE HTTP 服务端口--auto-port：自动化 websocket 端口
这两个端口不能混用。WEAPP_WS_ENDPOINT 必须指向自动化 websocket 端口，而不是 IDE HTTP 端口。
Codex / agent 使用规则
Related MCP Servers
Adoption & maintenance
Factual signals from GitHub, npm, and our automated checks — not a rating.
GitHub stars
15
Stargazers on the source repository.
npm downloads
659
Package downloads in the last 30 days.
Last commit
2mo ago
Most recent push to the default branch.
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about Weapp Agent MCP
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/weapp-agent-mcp)HTML Embed
<a href="https://allmcps.com/mcp/weapp-agent-mcp"><img src="https://allmcps.com/api/badge/weapp-agent-mcp?style=directory" alt="Weapp Agent MCP on AllMCPs" /></a>Technical Specs & Signals
CategoryDeveloper Tools
4/4 checks healthy over the last 46d
45Quality signal: Fair · 45/100How this signal is calculated ▾
Server availabilityNot measured
Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.
Verified ownership10/20
Documentation & tools16/30
Adoption & activity8/15
Community engagement0/10
A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.
Supply-chain signal
No high-severity advisories surfaced by our automated scan.
Critical 0High 0Medium 0Low 0
Scanned 3d ago via OSV.dev · @chaixueyuan/weapp-agent-mcp (npm)
Own this project?
This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.
Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.
Claim & get free dofollowShare & Embed
Add our SVG badge (dark/light directory styles) or embeddable widget to your site.