Skip to main content
Glama
weixin-devtools-mcp

weixin-devtools-mcp

by wooter-s

WeChat DevTools MCP

English | 简体中文

Let Codex and other coding agents inspect, interact with, and debug running WeChat Mini Programs through the Model Context Protocol.

Version Tests Quality License

Why this project

A coding agent needs feedback from the running Mini Program to verify its changes. This server exposes scoped page snapshots, element interactions, assertions, navigation, screenshots, console messages, and network requests through a local MCP connection to WeChat DevTools.

  • Explicit connections: choose a project, WebSocket endpoint, browser URL, or discovery request.

  • Scoped elements: opaque ref tokens and locator path segments traverse custom components.

  • Predictable results: all tools return a schemaVersion: "2.0" success/error envelope.

  • Optional collectors: console and network monitoring start only when their categories are enabled.

  • Small default surface: core exposes 20 tools; minimal exposes 10; full exposes 31.

Related MCP server: weapp-agent-mcp

Release status

The source tree is a 0.7.0 release candidate. npm latest is currently 0.6.0. Use the source configuration below for the 0.7 API until its Release is published. The version badge identifies this source tree, not a completed publication.

0.7 changes connection arguments, element targets, and result envelopes. Read the 0.6 → 0.7 migration guide before upgrading.

Requirements

  • Node.js 22 or newer.

  • WeChat DevTools installed, signed in, with CLI service access enabled.

  • A Mini Program project that compiles and opens in DevTools.

  • An MCP client supporting local stdio, such as Codex or Claude Desktop.

Unit CI covers Linux, Windows, and macOS on Node 22/24. That does not certify real DevTools operation on all those platforms. Real runtime verification is performed separately on a maintainer's desktop; see validation status.

Quick start with Codex

Build the source:

git clone https://github.com/wooter-s/weixin-devtools-mcp.git
cd weixin-devtools-mcp
npm ci
npm run build

Register the built server, replacing the absolute path:

codex mcp add weixin-devtools -- node /absolute/path/to/weixin-devtools-mcp/build/server.js --enable-categories=console,network,debug

Run codex mcp list, then start a Codex session in your Mini Program project. Open /mcp to check availability. Ask:

Connect to the Mini Program at /absolute/path/to/project. Read its page snapshot, identify the visible controls, and report the current page. Use explicit project connection; do not discover another project.

For a self-contained example, use tests/fixtures/monitoring-app from this repository. Follow the fixture setup first.

For an already published npm version, configure npx -y weixin-devtools-mcp@VERSION instead of the local Node entry. Do not assume an unpublished source version is available on npm. Detailed Codex configuration and reproducible demo includes the first tool calls and expected results.

Claude Desktop

Use the same built entry in your client configuration:

{
  "mcpServers": {
    "weixin-devtools-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/weixin-devtools-mcp/build/server.js"]
    }
  }
}

Tool profiles

Profile/category

Tools and behavior

core (default, 20)

Connection, page snapshots, locating, interactions, assertions, navigation, scripts

minimal (10)

Reduced tool surface

full (31)

All tools, including console, network, and debug

console

List console messages; inspect one message

network

List/inspect requests; stop monitoring; clear requests

debug

Screenshots and environment/connection/page diagnostics

Set --tools-profile=full, or add categories with --enable-categories=console,network,debug. Disable categories with --disable-categories=.... Environment equivalents are WEIXIN_MCP_TOOLS_PROFILE, WEIXIN_MCP_ENABLE_CATEGORIES, and WEIXIN_MCP_DISABLE_CATEGORIES.

Snapshots contain a scopes/edges graph. Use returned refs without parsing them; refresh observations after page changes. A path identifies elements through page/component scopes. See the public API examples.

Verification and limitations

npm run typecheck
npm run typecheck:test
npm test
npm run lint
npm run build
npm run lint:links
npm run test:coverage
npm run test:package

Coverage counts all production TypeScript under src/. CI retains HTML, JSON, and LCOV reports. Thresholds are 75% statements/functions/lines and 70% branches; we do not claim an unmeasured 80% coverage rate.

Real tests require a working, logged-in DevTools installation:

npm run test:integration:public
npm run test:integration

The public fixture is independent of private business projects. npm run test:integration:mpx is a separate, explicitly configured Mpx compatibility check. Native, Mpx, synthetic, and unit results are reported separately. A runtime prerequisite failure is a failure, not a passing skipped test.

Known release blocker: independent project startup on the previously tested DevTools 2.02.2607271 reports missing SDKVersion. A recording of a successful end-to-end demo is not yet available. Current evidence and release readiness live in the validation report; historical reports retain their original scope.

Documentation and contributing

Report reproducible bugs at GitHub Issues. Contributions from any supported client are welcome; keep AI assistance and human verification accurately attributed.

MIT licensed. Built on MCP, miniprogram-automator, with architectural inspiration from chrome-devtools-mcp.

Available Tools

20 tools
assert_attributeC

断言元素属性值

Inputs: target (required), attributeKey (required), attributeValue (required). Returns: ok, code, data, meta, +6 more

assert_stateC

断言元素的各种状态

Inputs: target (required), checked, enabled, focused, +1 more. Returns: ok, code, data, meta, +6 more

assert_textC

断言元素文本内容

Inputs: target (required), text, textMatches, textContains. Returns: ok, code, data, meta, +6 more

clickC

点击指定 target 的页面元素

Inputs: target (required), dblClick. Returns: ok, code, data, meta, +6 more

connect_devtoolsC

连接一个明确的微信开发者工具目标;project 固定按 launch → connect 尝试

Inputs: target (required), timeoutMs, healthCheck. Returns: ok, code, data, meta, +6 more

disconnect_devtoolsA

断开与微信开发者工具的连接并清理上下文状态

Inputs: no named parameters. Returns: ok, code, data, meta, +6 more

evaluate_scriptA

在小程序 AppService 上下文中执行 JavaScript 代码并返回结果。 支持访问 wx API、getApp()、getCurrentPages() 等小程序全局对象。 返回值必须是 JSON 可序列化的类型。

Inputs: function (required), args. Returns: ok, code, data, meta, +6 more

find_elementsA

在 Page 根作用域通过 selector、id、testId、dataId 或 text 查找元素并返回 opaque ref

Inputs: locator (required). Returns: ok, code, data, meta, +6 more

get_connection_statusA

获取连接、工具 profile 与监听生命周期状态

Inputs: refreshHealth. Returns: ok, code, data, meta, +6 more

get_current_pageA

获取当前页面信息并设置为活动页面

Inputs: no named parameters. Returns: ok, code, data, meta, +6 more

get_page_snapshotC

获取 Page 或自定义组件的 V2 scopes/edges 作用域图(默认预算 4/64/1000)

Inputs: root, budget, format, filePath, +2 more. Returns: ok, code, data, meta, +6 more

get_valueC

获取元素的值或文本内容

Inputs: target (required), attribute. Returns: ok, code, data, meta, +6 more

input_textC

向input/textarea元素输入文本

Inputs: mode (required), target (required), text. Returns: ok, code, data, meta, +6 more

reconnect_devtoolsB

不传参数时完整复用上次成功请求;传入 target 时以完整新请求替换

Inputs: target, timeoutMs, healthCheck. Returns: ok, code, data, meta, +6 more

relaunchB

重新启动小程序并跳转到指定页面

Inputs: url (required), params, timeout, waitForLoad. Returns: ok, code, data, meta, +6 more

set_form_controlC

设置表单控件的值(如picker、switch、slider等)

Inputs: value (required), target (required), trigger. Returns: ok, code, data, meta, +6 more

switch_tabC

切换到指定Tab页

Inputs: url (required), timeout, waitForLoad. Returns: ok, code, data, meta, +6 more

wait_forC

等待条件满足,支持等待元素出现、消失、文本匹配等

Inputs: text, delay, target, timeout, +2 more. Returns: ok, code, data, meta, +6 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools target distinct actions (click, input_text, navigate_to, evaluate_script), but reconnect_devtools and connect_devtools overlap in purpose, and get_value vs assert_text could be confused for reading element content.

    Naming Consistency4/5

    Tool names mostly follow a verb_noun pattern (connect_devtools, get_current_page, input_text, navigate_back), with a few exceptions like relaunch and wait_for that are verb-only but still clear.

    Tool Count4/5

    20 tools is on the higher end but appropriate for a WeChat devtools automation server covering connection, navigation, element interaction, assertions, and script evaluation.

    Completeness4/5

    The surface covers connection lifecycle, page navigation, element finding/interaction, assertions, and script evaluation. Minor gaps include no explicit screenshot or element clear/delete operation, but core automation workflows are well covered.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to control WeChat mini-programs running in WeChat Developer Tools through MCP tools. Provides automation capabilities for launching, navigating, querying, and interacting with pages and elements.
      61
      1
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to debug and control WeChat Mini Programs through WeChat DevTools, including direct automator operations and CLI-backed features like screenshots, logs, previews, and uploads.
      -